@betarena/ad-engine 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@betarena/ad-engine",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"private": false,
 	"description": "Betarena ad-engine widget",
 	"keywords": [

package/src/lib/Advert-Engine-Widget.svelte

@@ -141,7 +141,36 @@
      * @description
      * 📝 `Map` where, `key=CreativeId` and `value=AdvertObject` (temporary)
      */
-    mapCreative = new Map < number, AdsCreativeMain > ()
+    mapCreative = new Map < number, AdsCreativeMain > (),
+    /**
+     * @description
+     * 📝 Shared promise for one-time prerequisite initialization (device type + geolocation).
+     * Set on first call to `ensureReady()`; subsequent callers await the same promise.
+     */
+    readinessPromise: Promise < void > | null = null,
+    /**
+     * @description
+     * 📝 ID of the deferred `initialize()` timeout, used to cancel it if the component
+     * is destroyed before the delay elapses.
+     */
+    initTimeoutId: ReturnType < typeof setTimeout > | null = null,
+    /**
+     * @description
+     * 📝 Set to `true` once `onDestroy` fires, so any in-flight async work can bail out.
+     */
+    isDestroyed = false,
+    /**
+     * @description
+     * 📝 Incremented on each `refreshAds()` call. Passed into `injectBetarenaAds()`
+     * so that a superseded refresh can bail out after its network awaits complete.
+     */
+    refreshSerial = 0,
+    /**
+     * @description
+     * 📝 Previous value of `window.betarenaAdEngine` saved before this instance assigns it,
+     * so it can be restored on destroy instead of unconditionally deleting.
+     */
+    prevWindowApi: unknown = undefined
   ;
 
   const
@@ -168,7 +197,7 @@
 
   /**
    * @author
-   *  @migbash
+   *  @jonsnowpt
    * @summary
    *  🟥 MAIN
    * @description
@@ -177,16 +206,44 @@
    */
   function generateElementMap
   (
+    rootElement?: ParentNode
   ): void
   {
+    mapBetarenaAdvertStandardElement.clear();
+
     const
       /**
        * @description
        * 📝  `List` of `HTMLElements` identified on `page` expecting a target `zone` advertisement injection.
        */
-      listElementTarget = document.querySelectorAll('[data-betarena-zone-id]')
+      listElementTarget = (rootElement ?? document).querySelectorAll('[data-betarena-zone-id]')
     ;
 
+    // ╭─────
+    // │ NOTE:
+    // │ |: querySelectorAll only returns descendants — if rootElement itself carries
+    // │ |:   the zone attribute it would be missed. Include it explicitly.
+    // ╰─────
+    if (rootElement instanceof Element && rootElement.hasAttribute('data-betarena-zone-id'))
+    {
+      const
+        value = rootElement.getAttribute('data-betarena-zone-id')
+      ;
+
+      if (value)
+      {
+        for (const rawToken of value.split(','))
+        {
+          const
+            token = rawToken.trim(),
+            id = Number.parseInt(token, 10)
+          ;
+          if (!token || !Number.isFinite(id)) continue;
+          mapBetarenaAdvertStandardElement.set(id, rootElement);
+        }
+      }
+    }
+
     // [🐞]
     logger
     (
@@ -219,23 +276,14 @@
         ]
       );
 
-      if (value.includes(','))
+      for (const rawToken of value.split(','))
       {
         const
-          /**
-           * @description
-           * 📝 Split value by `,`
-           */
-          values = value.split(',')
+          token = rawToken.trim(),
+          id = Number.parseInt(token, 10)
         ;
-
-        for (const val of values)
-          mapBetarenaAdvertStandardElement.set(parseInt(val), elem);
-        ;
-      }
-      else
-      {
-        mapBetarenaAdvertStandardElement.set(parseInt(value), elem);
+        if (!token || !Number.isFinite(id)) continue;
+        mapBetarenaAdvertStandardElement.set(id, elem);
       }
     }
 
@@ -254,7 +302,7 @@
 
   /**
    * @author
-   *  @migbash
+   *  @jonsnowpt
    * @summary
    *  🟦 HELPER
    * @description
@@ -265,7 +313,9 @@
    */
   async function injectBetarenaAds
   (
-    opts: IAdsServiceData['request']['body']
+    opts: IAdsServiceData['request']['body'],
+    includesGlobalZone: boolean,
+    refreshToken: number
   ): Promise < void >
   {
     if (!document) return;
@@ -315,6 +365,8 @@
       ]
     );
 
+    if (isDestroyed || refreshToken !== refreshSerial) return;
+
     storeSession.updateData
     (
       [
@@ -363,7 +415,17 @@
     // ╰─────
     for (const [zoneId, element] of mapBetarenaAdvertStandardElement)
     {
-      if (!geoLocation) continue;
+      const
+        el = element as HTMLElement,
+        parent = el.parentElement as HTMLElement | null,
+        mountedAttr =
+        [
+          el.dataset.betarenaAdMounted,
+          parent?.dataset?.betarenaAdMounted
+        ].filter(Boolean).join(','),
+        mountedZones = mountedAttr.split(',').map(z => z.trim()).filter(Boolean)
+      ;
+      if (mountedZones.includes(String(zoneId))) continue;
 
       const
         /**
@@ -443,6 +505,11 @@
             }
           );
         ;
+        if (creativeAdData.length > 0)
+        {
+          mountedZones.push(String(zoneId));
+          el.dataset.betarenaAdMounted = mountedZones.join(',');
+        }
       }
       else if (zoneId == 2 || zoneId == 3)
       {
@@ -459,9 +526,16 @@
             }
           );
         ;
+        if (creativeAdData.length > 0)
+        {
+          mountedZones.push(String(zoneId));
+          el.dataset.betarenaAdMounted = mountedZones.join(',');
+        }
       }
       else if (zoneId == 4)
       {
+        if (!element.parentElement) continue;
+
         for (const adData of (creativeAdData ?? []))
           new AdvertLeftSide
           (
@@ -474,6 +548,29 @@
             }
           );
         ;
+        if (creativeAdData.length > 0)
+        {
+          mountedZones.push(String(zoneId));
+          el.dataset.betarenaAdMounted = mountedZones.join(',');
+          // ╭─────
+          // │ NOTE:
+          // │ |: Also mark the actual injection target (parentElement) so that
+          // │ |:   if the zone element is replaced while the parent persists,
+          // │ |:   subsequent refreshAds() calls won't re-inject into the same parent.
+          // ╰─────
+          if (element.parentElement)
+          {
+            const
+              parentMountedRaw = (element.parentElement as HTMLElement).dataset.betarenaAdMounted ?? '',
+              parentMountedZones = parentMountedRaw.split(',').map(z => z.trim()).filter(Boolean)
+            ;
+            if (!parentMountedZones.includes(String(zoneId)))
+            {
+              parentMountedZones.push(String(zoneId));
+              (element.parentElement as HTMLElement).dataset.betarenaAdMounted = parentMountedZones.join(',');
+            }
+          }
+        }
       }
     }
 
@@ -482,8 +579,11 @@
     // │ |: for case of injection of 'GLOBAL' placements for adverts,
     // │ |:   ⦿ (a.k.a SLIDER / POPUP ads)
     // │ |:   ⦿ (a.k.a document.body injections)
+    // │ |: `includesGlobalZone` is computed from the caller's original scope in refreshAds()
+    // │ |:   (not from DOM-filtered targetZoneIds) so global placements inject correctly
+    // │ |:   even when no zone-1 element exists in the DOM.
     // ╰─────
-    if (authorId || authorArticleTagIds.length > 0)
+    if (includesGlobalZone && (authorId || authorArticleTagIds.length > 0))
     {
       // ╭─────
       // │ NOTE:
@@ -658,8 +758,9 @@
     // │ |: BUT, data for ADS was still successfully fetched
     // │ |:   ⦿ (a.k.a Advert Condition was RETRIEVED/HIT).
     // │ |: Inject STANDARD SLIDER adverts in 'document.body'
+    // │ |: Guard with `includesGlobalZone` to avoid body injections on scoped refreshes.
     // ╰─────
-    else
+    else if (includesGlobalZone)
     {
       // [🐞]
       logger
@@ -699,7 +800,129 @@
 
   /**
    * @author
-   *  @migbash
+   *  @jonsnowpt
+   * @summary
+   *  🟦 HELPER
+   * @description
+   *  📝 Ensures prerequisites (`deviceType`, `geoLocation`) are resolved exactly once.
+   *  Callers that race — whether `initialize()` or an external `refreshAds()` — all
+   *  await the same in-flight promise.
+   * @returns { Promise < void > }
+   */
+  async function ensureReady
+  (
+  ): Promise < void >
+  {
+    if (readinessPromise) return readinessPromise;
+
+    readinessPromise =
+    (
+      async () =>
+      {
+        try
+        {
+          deviceType = detectDeviceWithUA() as IDeviceType;
+          geoLocation = await getUserLocation();
+        }
+        catch (e)
+        {
+          readinessPromise = null;
+          throw e;
+        }
+      }
+    )();
+
+    return readinessPromise;
+  }
+
+  /**
+   * @author
+   *  @jonsnowpt
+   * @summary
+   *  🟥 MAIN
+   * @description
+   *  📝 Re-scans the DOM for ad zone elements and injects ads for any that have not
+   *  yet been mounted. Safe to call multiple times — already-injected nodes store a
+   *  comma-separated list of mounted zone IDs in `data-betarena-ad-mounted`
+   *  (e.g. `"1,2"`), and zones whose ID is present in that list are skipped.
+   * @param {{ zoneIds?: number[]; rootElement?: HTMLElement }} [opts]
+   *  💠 Optional scope: restrict to specific zone IDs and / or a DOM subtree.
+   * @returns { Promise < void > }
+   */
+  async function refreshAds
+  (
+    opts?:
+    {
+      zoneIds?: number[];
+      rootElement?: HTMLElement;
+    }
+  ): Promise < void >
+  {
+    if (isDestroyed) return;
+
+    const
+      mySerial = ++refreshSerial
+    ;
+
+    await ensureReady();
+
+    if (isDestroyed || mySerial !== refreshSerial) return;
+
+    generateElementMap(opts?.rootElement);
+
+    let
+      /**
+       * @description
+       * 📝 Zone IDs discovered in the current DOM scan (or filtered subset).
+       */
+      targetZoneIds = [...mapBetarenaAdvertStandardElement.keys()]
+    ;
+
+    if (opts?.zoneIds && opts.zoneIds.length > 0)
+      targetZoneIds = targetZoneIds.filter(id => opts.zoneIds!.includes(id));
+    ;
+
+    // ╭─────
+    // │ NOTE:
+    // │ |: Only tear down previously injected global/body components when the
+    // │ |:   refresh scope includes zone 1 (the global placement zone) or when
+    // │ |:   no zone filter was applied (full refresh).
+    // │ |:   Scoped refreshes that exclude zone 1 leave existing body-mounted
+    // │ |:   widgets untouched to avoid permanently removing them.
+    // ╰─────
+    if (!opts?.zoneIds || opts.zoneIds.length === 0 || opts.zoneIds.includes(1))
+    {
+      for (const item of listAdWidgetElements)
+        item.$destroy();
+      ;
+      listAdWidgetElements.length = 0;
+    }
+
+    await injectBetarenaAds
+    (
+      {
+        deviceType,
+        isoCountryCode: geoLocation?.country_code ?? 'EN',
+        authorId,
+        tagIds: authorArticleTagIds,
+        zoneIds: targetZoneIds
+      },
+      // ╭─────
+      // │ NOTE:
+      // │ |: Derived from the caller's originally requested scope, NOT targetZoneIds
+      // │ |:   (which is DOM-filtered). If the DOM has no zone-1 element, targetZoneIds
+      // │ |:   won't include 1, but a full/zone-1 refresh should still inject global placements.
+      // ╰─────
+      !opts?.zoneIds || opts.zoneIds.length === 0 || opts.zoneIds.includes(1),
+      mySerial
+    );
+
+    return;
+  }
+
+  /**
+   * @author
+   *  @jonsnowpt
    * @summary
    *  🟥 MAIN
    * @description
@@ -710,10 +933,6 @@
   (
   ): Promise < void >
   {
-    deviceType = detectDeviceWithUA() as IDeviceType;
-    geoLocation = await getUserLocation();
-    generateElementMap();
-
     // [🐞]
     logger
     (
@@ -722,18 +941,7 @@
       ]
     );
 
-    injectBetarenaAds
-    (
-      {
-        deviceType,
-        // deviceType: 'desktop',
-        isoCountryCode: geoLocation.country_code ?? 'EN',
-        // isoCountryCode: 'BR',
-        authorId,
-        tagIds: authorArticleTagIds,
-        zoneIds: [...mapBetarenaAdvertStandardElement.keys()]
-      }
-    );
+    await refreshAds();
 
     return;
   }
@@ -756,9 +964,37 @@
       betarenaAdEngineStore.useLocalStorage();
       // ╭─────
       // │ NOTE:
+      // │ |: Expose public API immediately so host apps can call refreshAds()
+      // │ |: without waiting for the delayed initialize().
+      // │ |: refreshAds() self-initializes prerequisites via ensureReady() if needed.
+      // │ |: Save any existing value so it can be restored when this instance is destroyed.
+      // ╰─────
+      prevWindowApi = (window as any).betarenaAdEngine;
+      (window as any).betarenaAdEngine = { refreshAds };
+      // ╭─────
+      // │ NOTE:
       // │ |: Delay initialization to ensure all elements are loaded on page
       // ╰─────
-      setTimeout(() => { initialize(); return; }, 1000);
+      initTimeoutId = setTimeout
+      (
+        () =>
+        {
+          initialize().catch
+          (
+            (error) =>
+            {
+              logger
+              (
+                [
+                  '🚨 checkpoint ➤ initialize(..) // UNHANDLED ERROR',
+                  `🔹 [var] ➤ error ${error}`
+                ]
+              );
+            }
+          );
+        },
+        1000
+      );
       return;
     }
   );
@@ -776,6 +1012,25 @@
         ],
       );
 
+      isDestroyed = true;
+
+      if (initTimeoutId !== null)
+        clearTimeout(initTimeoutId);
+      ;
+
+      // ╭─────
+      // │ NOTE:
+      // │ |: Only remove/restore the global if this instance still owns it.
+      // │ |:   A later-mounted instance or host code may have overwritten it.
+      // ╰─────
+      if ((window as any).betarenaAdEngine?.refreshAds === refreshAds)
+      {
+        if (prevWindowApi !== undefined)
+          (window as any).betarenaAdEngine = prevWindowApi;
+        else
+          delete (window as any).betarenaAdEngine;
+      }
+
       // ╭─────
       // │ NOTE:
       // │ |: Destroy all dynamically created advert components