react-native-buzzvil-ad 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Conventional Commits](https://www.conventionalcommits.org/) and
+[Keep a Changelog](https://keepachangelog.com/); this project adheres to
+[Semantic Versioning](https://semver.org/).
+
+> **Unofficial package.** `react-native-buzzvil-ad` is community-maintained and
+> is **not** affiliated with, endorsed by, or supported by Buzzvil.
+
+## 0.2.0 (2026-06-13)
+
+### Features
+
+- **interstitial:** add Buzzvil BuzzBenefit v6 interstitial ads (full-screen
+  `dialog` / `bottomSheet`) on Android & iOS — `loadInterstitial(unitId, type?)`
+  (resolves on load, rejects on failure), `showInterstitial(unitId)`, and the
+  `onInterstitialClosed` event via `addInterstitialClosedListener(unitId, cb)`.
+  Built on the existing `Buzzvil` TurboModule using a New-Architecture typed
+  `EventEmitter`; native instances are tracked per `unitId`. (#5)
+- **example:** add interstitial smoke-test controls (type toggle, load/show,
+  close-event log) to the example app. (#5)
+
+### Bug Fixes
+
+- **interstitial:** reject a new `loadInterstitial` while an instance for the
+  same `unitId` is still loaded or showing, so the previous ad's close can no
+  longer remove a newer instance (and, on iOS, can no longer deallocate a
+  currently-visible ad). (#5)
+
+### Build / Dependencies
+
+- **deps:** resolve OSV-Scanner advisories (all dev-only, not shipped) — bump
+  `joi` to 17.13.4 (#2), pin `esbuild` `^0.28.1` via `resolutions`, and document
+  the `fast-xml-parser` suppression in `osv-scanner.toml`. (#4)
+
+## 0.1.0 (2026-06-13)
+
+Initial public release as the unofficial `react-native-buzzvil-ad` package
+(renamed from the scoped `@dongminyu/react-native-buzzvil`).
+
+### Features
+
+- **session:** BuzzBenefit v6 session API via the `Buzzvil` TurboModule —
+  `initialize`, `login`, `logout`, `isLoggedIn`, and `showBenefitHub` (the
+  BenefitHub offerwall), with a primitives-only spec + sentinel contract.
+- **native-ad:** `BuzzvilNativeAdView` Fabric component for in-feed native ads
+  on Android & iOS — inventory-size layout variants (banner / card), self-sizing
+  wrapper, and `onAdLoaded` / `onAdFailed` / `onAdClicked` / `onImpressed` /
+  `onRewarded` events. iOS calls the Swift SDK directly from Objective-C++
+  (no shim).
+- **login:** dev-mode warnings for non-PII / malformed `userId` values (Buzzvil
+  rejects emails and other identifiable ids).
+
+### Documentation
+
+- Add the SDK API-mapping spec, the ad-format expansion design, and project
+  guidance (`CLAUDE.md`) covering the two native surfaces.

package/android/src/main/java/com/buzzvil/BuzzvilModule.kt

@@ -1,6 +1,7 @@
 package com.buzzvil
 
 import android.app.Application
+import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.Promise
 import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.UiThreadUtil
@@ -12,6 +13,9 @@ import com.buzzvil.buzzbenefit.BuzzBenefitConfig
 import com.buzzvil.buzzbenefit.benefithub.BuzzBenefitHub
 import com.buzzvil.buzzbenefit.benefithub.BuzzBenefitHubConfig
 import com.buzzvil.buzzbenefit.benefithub.BuzzBenefitHubPage
+import com.buzzvil.buzzbenefit.BuzzAdError
+import com.buzzvil.buzzbenefit.interstitial.BuzzInterstitial
+import com.buzzvil.buzzbenefit.interstitial.BuzzInterstitialListener
 import com.buzzvil.sdk.BuzzvilSdk
 import com.buzzvil.sdk.BuzzvilSdkLoginListener
 import com.buzzvil.sdk.BuzzvilSdkUser
@@ -84,6 +88,85 @@ class BuzzvilModule(
     }
   }
 
+  // --- Interstitial ---
+
+  // Design Decision 1: one BuzzInterstitial instance per unitId, so a later
+  // showInterstitial(unitId) presents the instance loaded by loadInterstitial.
+  private val interstitials = mutableMapOf<String, BuzzInterstitial>()
+
+  override fun loadInterstitial(
+    unitId: String,
+    type: String,
+    promise: Promise,
+  ) {
+    // Reject a new load while an instance for this unitId already exists — in
+    // flight, loaded-and-waiting-to-show, or currently showing (parity with iOS).
+    // Overwriting interstitials[unitId] would let the OLD instance's onAdClosed
+    // remove the NEW one by unitId, no-op'ing the next show(). The entry is
+    // cleared on close/failure, after which a fresh load is allowed.
+    if (interstitials.containsKey(unitId)) {
+      promise.reject(
+        "buzzvil_interstitial_load_failed",
+        "An interstitial for this unitId is already loaded or loading; wait for onInterstitialClosed before loading again.",
+      )
+      return
+    }
+    // type sentinel: "bottomSheet" → bottom sheet; "dialog"/""/unknown → dialog.
+    val builder = BuzzInterstitial.Builder(unitId)
+    val interstitial =
+      if (type == "bottomSheet") builder.buildBottomSheet() else builder.buildDialog()
+    if (interstitial == null) {
+      promise.reject(
+        "buzzvil_interstitial_load_failed",
+        "Failed to build a BuzzInterstitial for unitId=$unitId.",
+      )
+      return
+    }
+    // Store from load-start; the guard above keys off its presence, and it's
+    // removed on close/failure.
+    interstitials[unitId] = interstitial
+
+    // The SDK listener can fire repeatedly; settle the promise exactly once.
+    var settled = false
+    interstitial.load(
+      object : BuzzInterstitialListener() {
+        override fun onAdLoaded() {
+          if (settled) return
+          settled = true
+          // Keep the instance in `interstitials` for the later show().
+          promise.resolve(null)
+        }
+
+        override fun onAdLoadFailed(error: BuzzAdError?) {
+          if (settled) return
+          settled = true
+          interstitials.remove(unitId)
+          promise.reject(
+            "buzzvil_interstitial_load_failed",
+            error?.message ?: error?.type?.toString() ?: "Interstitial load failed.",
+          )
+        }
+
+        override fun onAdClosed() {
+          // New-Arch typed EventEmitter: codegen generates this concrete emit
+          // method on the spec base; payload is a flat primitive map.
+          emitOnInterstitialClosed(Arguments.createMap().apply { putString("unitId", unitId) })
+          // Lifecycle: drop the dismissed instance so the map doesn't retain it
+          // (and so a fresh loadInterstitial for this unitId is allowed again).
+          interstitials.remove(unitId)
+        }
+      },
+    )
+  }
+
+  override fun showInterstitial(unitId: String) {
+    // show() presents UI — must run on the main thread (parity with BenefitHub).
+    UiThreadUtil.runOnUiThread {
+      val activity = currentActivity ?: return@runOnUiThread
+      interstitials[unitId]?.show(activity)
+    }
+  }
+
   companion object {
     const val NAME = NativeBuzzvilSpec.NAME
   }

package/ios/Buzzvil.h

@@ -1,5 +1,8 @@
 #import <BuzzvilSpec/BuzzvilSpec.h>
 
-@interface Buzzvil : NSObject <NativeBuzzvilSpec>
+// Subclass the codegen base (not bare NSObject): NativeBuzzvilSpecBase provides
+// setEventEmitterCallback: and the generated emitOnInterstitialClosed:, which
+// the interstitial "closed" event is dispatched through.
+@interface Buzzvil : NativeBuzzvilSpecBase <NativeBuzzvilSpec>
 
 @end

package/ios/Buzzvil.mm

@@ -8,7 +8,52 @@
 #import <BuzzvilSDK/BuzzvilSDK-Swift.h>
 #import <BuzzAdBenefitSDK/BuzzAdBenefitSDK-Swift.h>
 
-@implementation Buzzvil
+@class BuzzInterstitialLoader;
+
+/**
+ * Per-load helper that conforms to `BuzzInterstitialDelegate` and captures the
+ * promise blocks + `unitId` for one `loadInterstitial` call.
+ *
+ * Why a helper at all: `BuzzInterstitial.delegate` is a **weak** property and
+ * its delegate callbacks pass back the `BuzzInterstitial` (not the unitId). A
+ * dedicated loader (a) owns the `BuzzInterstitial` strongly so a later
+ * `showInterstitial` can present it, (b) carries the `unitId` directly so no
+ * instance→unitId reverse lookup is needed, and (c) is retained by the module's
+ * `_loaders` map so ARC doesn't dealloc it the moment `loadInterstitial`
+ * returns (which would silently drop every callback and hang the promise).
+ *
+ * The back-ref to the module is **weak** to avoid a retain cycle (the module is
+ * a long-lived TurboModule singleton). The module owns loader removal so a
+ * loader's final act is `[module removeLoaderForUnitId:]` — after which `self`
+ * may be deallocated, so callbacks touch nothing on `self` afterwards.
+ */
+@interface BuzzInterstitialLoader : NSObject <BuzzInterstitialDelegate>
+@property (nonatomic, strong) BuzzInterstitial *interstitial;
+@property (nonatomic, copy) NSString *unitId;
+@property (nonatomic, copy) RCTPromiseResolveBlock resolve;
+@property (nonatomic, copy) RCTPromiseRejectBlock reject;
+@property (nonatomic, assign) BOOL settled; // settle the promise exactly once
+@property (nonatomic, weak) Buzzvil *module;
+@end
+
+@implementation Buzzvil {
+  // unitId → loader. Retains each loader (and its BuzzInterstitial) from load
+  // until did-fail / did-dismiss removes it (parity with Android's map cleanup).
+  NSMutableDictionary<NSString *, BuzzInterstitialLoader *> *_loaders;
+}
+
+- (NSMutableDictionary<NSString *, BuzzInterstitialLoader *> *)loaders
+{
+  if (_loaders == nil) {
+    _loaders = [NSMutableDictionary new];
+  }
+  return _loaders;
+}
+
+- (void)removeLoaderForUnitId:(NSString *)unitId
+{
+  [self.loaders removeObjectForKey:unitId];
+}
 
 - (void)initialize:(NSString *)appId
 {
@@ -86,6 +131,61 @@
   });
 }
 
+#pragma mark - Interstitial
+
+- (void)loadInterstitial:(NSString *)unitId
+                    type:(NSString *)type
+                 resolve:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject
+{
+  // type sentinel: "bottomSheet" → bottom sheet; "dialog"/""/unknown → dialog
+  // (parity with Android's buildBottomSheet()/buildDialog()).
+  BuzzInterstitialType interstitialType =
+      [type isEqualToString:@"bottomSheet"] ? BuzzInterstitialTypeBottomSheet : BuzzInterstitialTypeDialog;
+
+  // Reject a new load while a loader for this unitId already exists — in flight,
+  // loaded-and-waiting-to-show, or currently showing (parity with Android).
+  // Overwriting self.loaders[unitId] would (a) let the OLD loader's didDismiss
+  // remove the NEW loader by unitId, and (b) dealloc the existing loader — and,
+  // as the sole strong owner of its BuzzInterstitial, dealloc a currently-visible
+  // interstitial. The entry is cleared on dismiss/failure, then a fresh load is OK.
+  BuzzInterstitialLoader *existing = self.loaders[unitId];
+  if (existing != nil) {
+    reject(@"buzzvil_interstitial_load_failed",
+           @"An interstitial for this unitId is already loaded or loading; wait for onInterstitialClosed before loading again.", nil);
+    return;
+  }
+
+  BuzzInterstitialLoader *loader = [BuzzInterstitialLoader new];
+  loader.unitId = unitId;
+  loader.resolve = resolve;
+  loader.reject = reject;
+  loader.module = self;
+  loader.interstitial = [[BuzzInterstitial alloc] initWithUnitId:unitId type:interstitialType];
+  loader.interstitial.delegate = loader; // delegate is weak — loader must outlive this call
+
+  // Retain the loader (and its BuzzInterstitial) until did-fail / did-dismiss.
+  self.loaders[unitId] = loader;
+
+  [loader.interstitial load];
+}
+
+- (void)showInterstitial:(NSString *)unitId
+{
+  // present presents UI — must run on the main thread (parity with BenefitHub).
+  dispatch_async(dispatch_get_main_queue(), ^{
+    UIViewController *presenter = RCTPresentedViewController();
+    if (presenter == nil) {
+      return;
+    }
+    BuzzInterstitialLoader *loader = self.loaders[unitId];
+    if (loader == nil) {
+      return; // nothing loaded for this unitId — no-op
+    }
+    [loader.interstitial presentOnViewController:presenter];
+  });
+}
+
 - (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
     (const facebook::react::ObjCTurboModule::InitParams &)params
 {
@@ -98,3 +198,44 @@
 }
 
 @end
+
+#pragma mark - BuzzInterstitialLoader
+
+@implementation BuzzInterstitialLoader
+
+- (void)buzzInterstitialDidLoadAd:(BuzzInterstitial *)interstitial
+{
+  if (self.settled) {
+    return;
+  }
+  self.settled = YES;
+  self.resolve(nil);
+  // Keep the loader in the map — showInterstitial needs it until dismiss.
+}
+
+- (void)buzzInterstitialDidFailToLoadAd:(BuzzInterstitial *)interstitial withError:(NSError *)error
+{
+  if (self.settled) {
+    return;
+  }
+  self.settled = YES;
+  // Capture before removal: removing from the map may dealloc self.
+  NSString *unitId = self.unitId;
+  RCTPromiseRejectBlock reject = self.reject;
+  Buzzvil *module = self.module;
+  reject(@"buzzvil_interstitial_load_failed", error.localizedDescription ?: @"Interstitial load failed.", error);
+  [module removeLoaderForUnitId:unitId]; // final act — touch nothing on self after this
+}
+
+- (void)buzzInterstitialDidDismiss:(UIViewController *)viewController
+{
+  // Capture before removal: removing from the map may dealloc self.
+  NSString *unitId = self.unitId;
+  Buzzvil *module = self.module;
+  // New-Arch typed EventEmitter: codegen generates emitOnInterstitialClosed on
+  // the spec base; payload is a flat NSDictionary { unitId } (parity with Android).
+  [module emitOnInterstitialClosed:@{@"unitId" : unitId}];
+  [module removeLoaderForUnitId:unitId]; // final act — touch nothing on self after this
+}
+
+@end

package/lib/module/NativeBuzzvil.js

@@ -2,6 +2,12 @@
 
 import { TurboModuleRegistry } from 'react-native';
 
+/**
+ * Payload for the interstitial "closed" event. Flat primitive (codegen events
+ * cannot carry nested objects); `unitId` identifies which placement closed so
+ * the JS wrapper can route the callback to the right listener.
+ */
+
 /**
  * TurboModule spec for the native `Buzzvil` module — a thin bridge over
  * Buzzvil's BuzzBenefit v6 SDKs (Android / iOS).

package/lib/module/NativeBuzzvil.js.map

@@ -1 +1 @@
-{"version":3,"names":["TurboModuleRegistry","getEnforcing"],"sourceRoot":"../../src","sources":["NativeBuzzvil.ts"],"mappings":";;AAAA,SAASA,mBAAmB,QAA0B,cAAc;;AAEpE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAiDA,eAAeA,mBAAmB,CAACC,YAAY,CAAO,SAAS,CAAC","ignoreList":[]}
+{"version":3,"names":["TurboModuleRegistry","getEnforcing"],"sourceRoot":"../../src","sources":["NativeBuzzvil.ts"],"mappings":";;AAAA,SAASA,mBAAmB,QAA0B,cAAc;;AAGpE;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AA0FA,eAAeA,mBAAmB,CAACC,YAAY,CAAO,SAAS,CAAC","ignoreList":[]}

package/lib/module/index.js

@@ -2,4 +2,5 @@
 
 export { initialize, login, logout, isLoggedIn, showBenefitHub } from './buzzvil';
 export { BuzzvilNativeAdView } from './BuzzvilNativeAdView';
+export { loadInterstitial, showInterstitial, addInterstitialClosedListener } from './interstitial';
 //# sourceMappingURL=index.js.map

package/lib/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["initialize","login","logout","isLoggedIn","showBenefitHub","BuzzvilNativeAdView"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":";;AAAA,SACEA,UAAU,EACVC,KAAK,EACLC,MAAM,EACNC,UAAU,EACVC,cAAc,QACT,WAAW;AAElB,SAASC,mBAAmB,QAAQ,uBAAuB","ignoreList":[]}
+{"version":3,"names":["initialize","login","logout","isLoggedIn","showBenefitHub","BuzzvilNativeAdView","loadInterstitial","showInterstitial","addInterstitialClosedListener"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":";;AAAA,SACEA,UAAU,EACVC,KAAK,EACLC,MAAM,EACNC,UAAU,EACVC,cAAc,QACT,WAAW;AAElB,SAASC,mBAAmB,QAAQ,uBAAuB;AAE3D,SACEC,gBAAgB,EAChBC,gBAAgB,EAChBC,6BAA6B,QACxB,gBAAgB","ignoreList":[]}

package/lib/module/interstitial.js

@@ -0,0 +1,23 @@
+"use strict";
+
+/**
+ * Web fallback. Buzzvil's interstitial is mobile-only, so the imperative
+ * methods fail **at call time** (never at import time). `.native.tsx` is used
+ * on iOS/Android.
+ */
+
+const UNSUPPORTED = 'react-native-buzzvil is not supported on web.';
+export function loadInterstitial(_unitId, _type = 'dialog') {
+  return Promise.reject(new Error(UNSUPPORTED));
+}
+export function showInterstitial(_unitId) {
+  throw new Error(UNSUPPORTED);
+}
+
+/** No-op on web: the close event never fires, so `remove()` does nothing. */
+export function addInterstitialClosedListener(_unitId, _cb) {
+  return {
+    remove() {}
+  };
+}
+//# sourceMappingURL=interstitial.js.map

package/lib/module/interstitial.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["UNSUPPORTED","loadInterstitial","_unitId","_type","Promise","reject","Error","showInterstitial","addInterstitialClosedListener","_cb","remove"],"sourceRoot":"../../src","sources":["interstitial.tsx"],"mappings":";;AAEA;AACA;AACA;AACA;AACA;;AAEA,MAAMA,WAAW,GAAG,+CAA+C;AAEnE,OAAO,SAASC,gBAAgBA,CAC9BC,OAAe,EACfC,KAAuB,GAAG,QAAQ,EACnB;EACf,OAAOC,OAAO,CAACC,MAAM,CAAC,IAAIC,KAAK,CAACN,WAAW,CAAC,CAAC;AAC/C;AAEA,OAAO,SAASO,gBAAgBA,CAACL,OAAe,EAAQ;EACtD,MAAM,IAAII,KAAK,CAACN,WAAW,CAAC;AAC9B;;AAEA;AACA,OAAO,SAASQ,6BAA6BA,CAC3CN,OAAe,EACfO,GAAe,EACK;EACpB,OAAO;IACLC,MAAMA,CAAA,EAAG,CAAC;EACZ,CAAC;AACH","ignoreList":[]}

package/lib/module/interstitial.native.js

@@ -0,0 +1,47 @@
+"use strict";
+
+import Buzzvil from "./NativeBuzzvil.js";
+/**
+ * Native (iOS/Android) implementation of the public Interstitial API. Wraps the
+ * primitive-only native spec (`./NativeBuzzvil`) in friendly functions; raw
+ * `NativeBuzzvil` calls stay out of the public surface.
+ *
+ * The native side holds one interstitial instance per `unitId` (design
+ * Decision 1), so `loadInterstitial` then `showInterstitial` operate on the
+ * same placement.
+ */
+
+/**
+ * Load an interstitial for `unitId`. Resolves once loaded, rejects on
+ * load failure.
+ *
+ * @param type `'dialog'` (default) or `'bottomSheet'`.
+ */
+export function loadInterstitial(unitId, type = 'dialog') {
+  return Buzzvil.loadInterstitial(unitId, type);
+}
+
+/** Present the interstitial previously loaded for `unitId`. */
+export function showInterstitial(unitId) {
+  Buzzvil.showInterstitial(unitId);
+}
+
+/**
+ * Subscribe to the "interstitial closed" event for a specific `unitId`. The
+ * native emitter is module-wide (one event for all placements), so the
+ * callback is gated on `event.unitId === unitId` — listeners for other units
+ * never fire. Returns a handle whose `remove()` unsubscribes.
+ */
+export function addInterstitialClosedListener(unitId, cb) {
+  const subscription = Buzzvil.onInterstitialClosed(event => {
+    if (event.unitId === unitId) {
+      cb();
+    }
+  });
+  return {
+    remove() {
+      subscription.remove();
+    }
+  };
+}
+//# sourceMappingURL=interstitial.native.js.map

package/lib/module/interstitial.native.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["Buzzvil","loadInterstitial","unitId","type","showInterstitial","addInterstitialClosedListener","cb","subscription","onInterstitialClosed","event","remove"],"sourceRoot":"../../src","sources":["interstitial.native.tsx"],"mappings":";;AAAA,OAAOA,OAAO,MAAM,oBAAiB;AAGrC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,gBAAgBA,CAC9BC,MAAc,EACdC,IAAsB,GAAG,QAAQ,EAClB;EACf,OAAOH,OAAO,CAACC,gBAAgB,CAACC,MAAM,EAAEC,IAAI,CAAC;AAC/C;;AAEA;AACA,OAAO,SAASC,gBAAgBA,CAACF,MAAc,EAAQ;EACrDF,OAAO,CAACI,gBAAgB,CAACF,MAAM,CAAC;AAClC;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASG,6BAA6BA,CAC3CH,MAAc,EACdI,EAAc,EACM;EACpB,MAAMC,YAAY,GAAGP,OAAO,CAACQ,oBAAoB,CAAEC,KAAK,IAAK;IAC3D,IAAIA,KAAK,CAACP,MAAM,KAAKA,MAAM,EAAE;MAC3BI,EAAE,CAAC,CAAC;IACN;EACF,CAAC,CAAC;EACF,OAAO;IACLI,MAAMA,CAAA,EAAG;MACPH,YAAY,CAACG,MAAM,CAAC,CAAC;IACvB;EACF,CAAC;AACH","ignoreList":[]}

package/lib/typescript/src/NativeBuzzvil.d.ts

@@ -1,4 +1,13 @@
 import { type TurboModule } from 'react-native';
+import type { CodegenTypes } from 'react-native';
+/**
+ * Payload for the interstitial "closed" event. Flat primitive (codegen events
+ * cannot carry nested objects); `unitId` identifies which placement closed so
+ * the JS wrapper can route the callback to the right listener.
+ */
+type InterstitialClosedEvent = Readonly<{
+    unitId: string;
+}>;
 /**
  * TurboModule spec for the native `Buzzvil` module — a thin bridge over
  * Buzzvil's BuzzBenefit v6 SDKs (Android / iOS).
@@ -66,6 +75,44 @@ export interface Spec extends TurboModule {
      * See the sentinel contract above for `routePath` / `showHistory`.
      */
     showBenefitHub(routePath: string, showHistory: boolean): void;
+    /**
+     * Load an interstitial ad for `unitId`. Resolves when the ad has loaded
+     * (Android `onAdLoaded` / iOS `BuzzInterstitialDidLoadAd`), rejects on
+     * load failure (`onAdLoadFailed` / `DidFail(toLoadAd:)`).
+     *
+     * The native side holds one `BuzzInterstitial` instance per `unitId` (see
+     * design Decision 1: a `unitId`-keyed map), so a later `showInterstitial`
+     * presents this loaded instance.
+     *
+     * @param unitId Interstitial ad unit id from the Buzzvil admin.
+     * @param type `'dialog'` or `'bottomSheet'` — selects the native build
+     *   variant (`buildDialog()` / `buildBottomSheet()`). Carried as a plain
+     *   string (no codegen enums); the friendly `InterstitialType` union and the
+     *   `'dialog'` default live in the JS wrapper (`./interstitial.native.tsx`).
+     */
+    loadInterstitial(unitId: string, type: string): Promise<void>;
+    /**
+     * Present the interstitial instance previously loaded for `unitId`. No-op if
+     * nothing is loaded. UI work — runs on the main thread (parity with
+     * `showBenefitHub`).
+     */
+    showInterstitial(unitId: string): void;
+    /**
+     * Fires when an interstitial is dismissed (Android `onAdClosed` / iOS
+     * `BuzzInterstitialDidDismiss`). The payload's `unitId` identifies which
+     * placement closed; the JS wrapper filters by it so each
+     * `addInterstitialClosedListener(unitId, …)` only fires for its own unit.
+     *
+     * Uses a codegen typed `EventEmitter` (RN New-Architecture event member):
+     * codegen generates a concrete `emitOnInterstitialClosed` on the native spec
+     * base class, so the native impl emits via that — no manual
+     * `addListener`/`removeListeners` plumbing. Imported as
+     * `CodegenTypes.EventEmitter` (the runtime `EventEmitter` exported from
+     * `react-native` is a class, not this type); codegen matches by the bare
+     * type name `EventEmitter`, so the `CodegenTypes.`-qualified form is
+     * recognized identically.
+     */
+    readonly onInterstitialClosed: CodegenTypes.EventEmitter<InterstitialClosedEvent>;
 }
 declare const _default: Spec;
 export default _default;

package/lib/typescript/src/NativeBuzzvil.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NativeBuzzvil.d.ts","sourceRoot":"","sources":["../../../src/NativeBuzzvil.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,IAAK,SAAQ,WAAW;IACvC;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhC;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExE,yDAAyD;IACzD,MAAM,IAAI,IAAI,CAAC;IAEf,wFAAwF;IACxF,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAE/B;;;;;;;OAOG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/D;;AAED,wBAAiE"}
+{"version":3,"file":"NativeBuzzvil.d.ts","sourceRoot":"","sources":["../../../src/NativeBuzzvil.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD;;;;GAIG;AACH,KAAK,uBAAuB,GAAG,QAAQ,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,IAAK,SAAQ,WAAW;IACvC;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhC;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExE,yDAAyD;IACzD,MAAM,IAAI,IAAI,CAAC;IAEf,wFAAwF;IACxF,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAE/B;;;;;;;OAOG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,IAAI,CAAC;IAE9D;;;;;;;;;;;;;;OAcG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9D;;;;OAIG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAEvC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,oBAAoB,EAAE,YAAY,CAAC,YAAY,CAAC,uBAAuB,CAAC,CAAC;CACnF;;AAED,wBAAiE"}

package/lib/typescript/src/index.d.ts

@@ -2,4 +2,6 @@ export { initialize, login, logout, isLoggedIn, showBenefitHub, } from './buzzvi
 export type { BuzzvilUser, BuzzvilGender, BenefitHubOptions } from './types.js';
 export { BuzzvilNativeAdView } from './BuzzvilNativeAdView';
 export type { BuzzvilNativeAdLayout, BuzzvilNativeAdViewProps } from './types.js';
+export { loadInterstitial, showInterstitial, addInterstitialClosedListener, } from './interstitial';
+export type { InterstitialType } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,KAAK,EACL,MAAM,EACN,UAAU,EACV,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAS,CAAC;AAC7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,YAAY,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,YAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,KAAK,EACL,MAAM,EACN,UAAU,EACV,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAS,CAAC;AAC7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,YAAY,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,YAAS,CAAC;AAC/E,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,6BAA6B,GAC9B,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAS,CAAC"}

package/lib/typescript/src/interstitial.d.ts

@@ -0,0 +1,8 @@
+import type { InterstitialType } from './types.js';
+export declare function loadInterstitial(_unitId: string, _type?: InterstitialType): Promise<void>;
+export declare function showInterstitial(_unitId: string): void;
+/** No-op on web: the close event never fires, so `remove()` does nothing. */
+export declare function addInterstitialClosedListener(_unitId: string, _cb: () => void): {
+    remove(): void;
+};
+//# sourceMappingURL=interstitial.d.ts.map

package/lib/typescript/src/interstitial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interstitial.d.ts","sourceRoot":"","sources":["../../../src/interstitial.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAS,CAAC;AAUhD,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,gBAA2B,GACjC,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEtD;AAED,6EAA6E;AAC7E,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,IAAI,GACd;IAAE,MAAM,IAAI,IAAI,CAAA;CAAE,CAIpB"}

package/lib/typescript/src/interstitial.native.d.ts

@@ -0,0 +1,29 @@
+import type { InterstitialType } from './types.js';
+/**
+ * Native (iOS/Android) implementation of the public Interstitial API. Wraps the
+ * primitive-only native spec (`./NativeBuzzvil`) in friendly functions; raw
+ * `NativeBuzzvil` calls stay out of the public surface.
+ *
+ * The native side holds one interstitial instance per `unitId` (design
+ * Decision 1), so `loadInterstitial` then `showInterstitial` operate on the
+ * same placement.
+ */
+/**
+ * Load an interstitial for `unitId`. Resolves once loaded, rejects on
+ * load failure.
+ *
+ * @param type `'dialog'` (default) or `'bottomSheet'`.
+ */
+export declare function loadInterstitial(unitId: string, type?: InterstitialType): Promise<void>;
+/** Present the interstitial previously loaded for `unitId`. */
+export declare function showInterstitial(unitId: string): void;
+/**
+ * Subscribe to the "interstitial closed" event for a specific `unitId`. The
+ * native emitter is module-wide (one event for all placements), so the
+ * callback is gated on `event.unitId === unitId` — listeners for other units
+ * never fire. Returns a handle whose `remove()` unsubscribes.
+ */
+export declare function addInterstitialClosedListener(unitId: string, cb: () => void): {
+    remove(): void;
+};
+//# sourceMappingURL=interstitial.native.d.ts.map

package/lib/typescript/src/interstitial.native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interstitial.native.d.ts","sourceRoot":"","sources":["../../../src/interstitial.native.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAS,CAAC;AAEhD;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,gBAA2B,GAChC,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,+DAA+D;AAC/D,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAErD;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,IAAI,GACb;IAAE,MAAM,IAAI,IAAI,CAAA;CAAE,CAWpB"}

package/lib/typescript/src/types.d.ts

@@ -13,6 +13,11 @@ export interface BuzzvilUser {
     /** 4-digit birth year, e.g. `1990`. */
     birthYear?: number;
 }
+/**
+ * Interstitial presentation style. `'dialog'` → `BuzzInterstitial.buildDialog()`;
+ * `'bottomSheet'` → `.buildBottomSheet()`. Carried to native as a plain string.
+ */
+export type InterstitialType = 'dialog' | 'bottomSheet';
 /** Options for presenting the BenefitHub (offerwall). */
 export interface BenefitHubOptions {
     /** BenefitHub page number from the Buzzvil admin (advanced routing). */

package/lib/typescript/src/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,kEAAkE;AAClE,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE9C,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,+DAA+D;AAC/D,MAAM,MAAM,qBAAqB,GAC7B,QAAQ,GACR,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,CAAC;AAEd,qEAAqE;AACrE,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,KAAK,CAAC,EAAE,OAAO,cAAc,EAAE,SAAS,CAAC,OAAO,cAAc,EAAE,SAAS,CAAC,CAAC;IAC3E,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC5D,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC5D,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;CAChD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,kEAAkE;AAClE,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE9C,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,aAAa,CAAC;AAExD,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,+DAA+D;AAC/D,MAAM,MAAM,qBAAqB,GAC7B,QAAQ,GACR,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,CAAC;AAEd,qEAAqE;AACrE,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,KAAK,CAAC,EAAE,OAAO,cAAc,EAAE,SAAS,CAAC,OAAO,cAAc,EAAE,SAAS,CAAC,CAAC;IAC3E,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC5D,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC5D,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;CAChD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-buzzvil-ad",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Unofficial, community-maintained React Native wrapper for the Buzzvil BuzzBenefit SDK (Android & iOS). Not affiliated with, endorsed by, or supported by Buzzvil.",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -20,6 +20,7 @@
     "cpp",
     "*.podspec",
     "react-native.config.js",
+    "CHANGELOG.md",
     "!ios/build",
     "!android/build",
     "!android/gradle",
@@ -88,6 +89,7 @@
     "react-native": "*"
   },
   "resolutions": {
+    "esbuild": "^0.28.1",
     "jest": "30.4.1",
     "jest-cli": "30.4.1",
     "@jest/core": "30.4.1",

package/src/NativeBuzzvil.ts

@@ -1,4 +1,12 @@
 import { TurboModuleRegistry, type TurboModule } from 'react-native';
+import type { CodegenTypes } from 'react-native';
+
+/**
+ * Payload for the interstitial "closed" event. Flat primitive (codegen events
+ * cannot carry nested objects); `unitId` identifies which placement closed so
+ * the JS wrapper can route the callback to the right listener.
+ */
+type InterstitialClosedEvent = Readonly<{ unitId: string }>;
 
 /**
  * TurboModule spec for the native `Buzzvil` module — a thin bridge over
@@ -71,6 +79,47 @@ export interface Spec extends TurboModule {
    * See the sentinel contract above for `routePath` / `showHistory`.
    */
   showBenefitHub(routePath: string, showHistory: boolean): void;
+
+  /**
+   * Load an interstitial ad for `unitId`. Resolves when the ad has loaded
+   * (Android `onAdLoaded` / iOS `BuzzInterstitialDidLoadAd`), rejects on
+   * load failure (`onAdLoadFailed` / `DidFail(toLoadAd:)`).
+   *
+   * The native side holds one `BuzzInterstitial` instance per `unitId` (see
+   * design Decision 1: a `unitId`-keyed map), so a later `showInterstitial`
+   * presents this loaded instance.
+   *
+   * @param unitId Interstitial ad unit id from the Buzzvil admin.
+   * @param type `'dialog'` or `'bottomSheet'` — selects the native build
+   *   variant (`buildDialog()` / `buildBottomSheet()`). Carried as a plain
+   *   string (no codegen enums); the friendly `InterstitialType` union and the
+   *   `'dialog'` default live in the JS wrapper (`./interstitial.native.tsx`).
+   */
+  loadInterstitial(unitId: string, type: string): Promise<void>;
+
+  /**
+   * Present the interstitial instance previously loaded for `unitId`. No-op if
+   * nothing is loaded. UI work — runs on the main thread (parity with
+   * `showBenefitHub`).
+   */
+  showInterstitial(unitId: string): void;
+
+  /**
+   * Fires when an interstitial is dismissed (Android `onAdClosed` / iOS
+   * `BuzzInterstitialDidDismiss`). The payload's `unitId` identifies which
+   * placement closed; the JS wrapper filters by it so each
+   * `addInterstitialClosedListener(unitId, …)` only fires for its own unit.
+   *
+   * Uses a codegen typed `EventEmitter` (RN New-Architecture event member):
+   * codegen generates a concrete `emitOnInterstitialClosed` on the native spec
+   * base class, so the native impl emits via that — no manual
+   * `addListener`/`removeListeners` plumbing. Imported as
+   * `CodegenTypes.EventEmitter` (the runtime `EventEmitter` exported from
+   * `react-native` is a class, not this type); codegen matches by the bare
+   * type name `EventEmitter`, so the `CodegenTypes.`-qualified form is
+   * recognized identically.
+   */
+  readonly onInterstitialClosed: CodegenTypes.EventEmitter<InterstitialClosedEvent>;
 }
 
 export default TurboModuleRegistry.getEnforcing<Spec>('Buzzvil');

package/src/index.tsx

@@ -8,3 +8,9 @@ export {
 export type { BuzzvilUser, BuzzvilGender, BenefitHubOptions } from './types';
 export { BuzzvilNativeAdView } from './BuzzvilNativeAdView';
 export type { BuzzvilNativeAdLayout, BuzzvilNativeAdViewProps } from './types';
+export {
+  loadInterstitial,
+  showInterstitial,
+  addInterstitialClosedListener,
+} from './interstitial';
+export type { InterstitialType } from './types';

package/src/interstitial.native.tsx

@@ -0,0 +1,52 @@
+import Buzzvil from './NativeBuzzvil';
+import type { InterstitialType } from './types';
+
+/**
+ * Native (iOS/Android) implementation of the public Interstitial API. Wraps the
+ * primitive-only native spec (`./NativeBuzzvil`) in friendly functions; raw
+ * `NativeBuzzvil` calls stay out of the public surface.
+ *
+ * The native side holds one interstitial instance per `unitId` (design
+ * Decision 1), so `loadInterstitial` then `showInterstitial` operate on the
+ * same placement.
+ */
+
+/**
+ * Load an interstitial for `unitId`. Resolves once loaded, rejects on
+ * load failure.
+ *
+ * @param type `'dialog'` (default) or `'bottomSheet'`.
+ */
+export function loadInterstitial(
+  unitId: string,
+  type: InterstitialType = 'dialog'
+): Promise<void> {
+  return Buzzvil.loadInterstitial(unitId, type);
+}
+
+/** Present the interstitial previously loaded for `unitId`. */
+export function showInterstitial(unitId: string): void {
+  Buzzvil.showInterstitial(unitId);
+}
+
+/**
+ * Subscribe to the "interstitial closed" event for a specific `unitId`. The
+ * native emitter is module-wide (one event for all placements), so the
+ * callback is gated on `event.unitId === unitId` — listeners for other units
+ * never fire. Returns a handle whose `remove()` unsubscribes.
+ */
+export function addInterstitialClosedListener(
+  unitId: string,
+  cb: () => void
+): { remove(): void } {
+  const subscription = Buzzvil.onInterstitialClosed((event) => {
+    if (event.unitId === unitId) {
+      cb();
+    }
+  });
+  return {
+    remove() {
+      subscription.remove();
+    },
+  };
+}

package/src/interstitial.tsx

@@ -0,0 +1,30 @@
+import type { InterstitialType } from './types';
+
+/**
+ * Web fallback. Buzzvil's interstitial is mobile-only, so the imperative
+ * methods fail **at call time** (never at import time). `.native.tsx` is used
+ * on iOS/Android.
+ */
+
+const UNSUPPORTED = 'react-native-buzzvil is not supported on web.';
+
+export function loadInterstitial(
+  _unitId: string,
+  _type: InterstitialType = 'dialog'
+): Promise<void> {
+  return Promise.reject(new Error(UNSUPPORTED));
+}
+
+export function showInterstitial(_unitId: string): void {
+  throw new Error(UNSUPPORTED);
+}
+
+/** No-op on web: the close event never fires, so `remove()` does nothing. */
+export function addInterstitialClosedListener(
+  _unitId: string,
+  _cb: () => void
+): { remove(): void } {
+  return {
+    remove() {},
+  };
+}

package/src/types.ts

@@ -16,6 +16,12 @@ export interface BuzzvilUser {
   birthYear?: number;
 }
 
+/**
+ * Interstitial presentation style. `'dialog'` → `BuzzInterstitial.buildDialog()`;
+ * `'bottomSheet'` → `.buildBottomSheet()`. Carried to native as a plain string.
+ */
+export type InterstitialType = 'dialog' | 'bottomSheet';
+
 /** Options for presenting the BenefitHub (offerwall). */
 export interface BenefitHubOptions {
   /** BenefitHub page number from the Buzzvil admin (advanced routing). */