novvy-ads-react-native 1.0.0-beta.1

package/src/NovvyAds.ts

@@ -0,0 +1,98 @@
+import { sha256 } from 'js-sha256';
+
+import { Native } from './eventBus';
+import type { NovvyUserContext, NovvyContentContext } from './types';
+
+/**
+ * SDK entry point for Novvy Ads.
+ *
+ * A **thin** surface — it only wraps the native SDK's top-level entry (init +
+ * user/content context + email hashing). Ads themselves are created and driven
+ * directly through their classes ({@link NovvyInterstitialAd},
+ * {@link NovvyRewardedAd}, {@link NovvyMidAd}, {@link NovvyEndAd},
+ * {@link NovvyScrollAd}, {@link NovvyPauseAd}); the host owns each instance and
+ * wires its per-ad callbacks. Mirrors the Flutter plugin's `NovvyAds`.
+ *
+ * ```ts
+ * // 1. Initialize once at app startup (optionally with a user profile).
+ * const ok = await NovvyAds.initialize({
+ *   appId: '...', endpoint: '...', apiKey: '...',
+ *   userContext: { userId: '...', isPaidUser: true },
+ * });
+ *
+ * // 2. Set / refresh content context (and user profile if not set above).
+ * NovvyAds.setContentContext({ seriesName: '...', episodeNumber: 1 });
+ *
+ * // 3. Create an ad, wire callbacks, load & show.
+ * const ad = new NovvyRewardedAd('...');
+ * let earned = false;
+ * ad.onAdLoaded = () => ad.show();
+ * ad.onUserEarnedReward = () => { earned = true; };
+ * ad.onAdDismissed = () => { if (earned) grantReward(); };
+ * ad.onAdFailedToLoad = () => {};
+ * ad.load();
+ * ```
+ */
+export const NovvyAds = {
+  /**
+   * Initialize the Novvy SDK. Must be called before creating any ads.
+   *
+   * Resolves with the native init-complete signal — `true` on success, `false`
+   * if initialization failed. May be called again (e.g. after login/logout);
+   * the native SDK handles re-initialization idempotently.
+   *
+   * @param userContext optional user-targeting context applied at init time
+   * (equivalent to calling {@link setUserContext} right after).
+   */
+  async initialize(options: {
+    appId: string;
+    endpoint: string;
+    apiKey: string;
+    userContext?: NovvyUserContext | null;
+  }): Promise<boolean> {
+    try {
+      return await Native.initialize(
+        options.appId,
+        options.endpoint,
+        options.apiKey,
+        options.userContext ?? null
+      );
+    } catch {
+      return false;
+    }
+  },
+
+  /**
+   * Hashes an email address using SHA-256 for privacy compliance. Use before
+   * passing an email to {@link NovvyUserContext.hashedEmail}. Pure JS — mirrors
+   * the native SDK's `helperHashEmail()`.
+   */
+  helperHashEmail(email: string): string {
+    return sha256(email.trim().toLowerCase());
+  },
+
+  /** Replaces the entire user context (null fields clear existing values). */
+  setUserContext(context: NovvyUserContext): void {
+    Native.setUserContext(context);
+  },
+
+  /** Incrementally merges user context fields (null fields preserve existing values). */
+  updateUserContext(partial: NovvyUserContext): void {
+    Native.updateUserContext(partial);
+  },
+
+  /**
+   * Replaces the entire content context (null fields clear existing values).
+   *
+   * Call before each `load()` / `attach()` in drama scenarios — the backend
+   * needs the current series/episode or it returns no fill.
+   */
+  setContentContext(context: NovvyContentContext): void {
+    Native.setContentContext(context);
+  },
+
+  /** Incrementally merges content context fields (null fields preserve existing values). */
+  updateContentContext(partial: NovvyContentContext): void {
+    Native.updateContentContext(partial);
+  },
+};

package/src/ads/NovvyAd.ts

@@ -0,0 +1,125 @@
+import { Native, subscribe } from '../eventBus';
+import type { NativeAdEvent } from '../spec/NativeNovvyAds';
+import { NovvyAdEvent } from '../types';
+
+/**
+ * Base class for all Novvy ad types.
+ *
+ * Mirrors the Flutter plugin's `NovvyAd` (lib/novvy_ads_plugin.dart).
+ * Instances are owned by the host: keep a reference alive until the ad
+ * completes (`onAdDismissed` / `onAdHidden`) and then call {@link destroy}.
+ */
+export abstract class NovvyAd {
+  readonly adUnitId: string;
+  private readonly _adObjectId: string;
+
+  protected _isReady = false;
+  protected _disposed = false;
+
+  private _unsubscribe: (() => void) | null = null;
+
+  /** Called when the ad has loaded successfully. */
+  onAdLoaded?: () => void;
+  /** Called when the ad fails to load / request. */
+  onAdFailedToLoad?: (error: string) => void;
+
+  constructor(adUnitId: string) {
+    this.adUnitId = adUnitId;
+    this._adObjectId = NovvyAd._generateUniqueId();
+  }
+
+  /** The unique object ID for this ad instance. */
+  get adObjectId(): string {
+    return this._adObjectId;
+  }
+
+  /** Whether the ad is loaded and ready to show. */
+  get isReady(): boolean {
+    return this._isReady;
+  }
+
+  /**
+   * Subscribes to this ad's native event stream (filtered by object ID).
+   * Idempotent.
+   */
+  protected _subscribe(): void {
+    if (this._unsubscribe) {
+      return;
+    }
+    this._unsubscribe = subscribe(this._adObjectId, (event) =>
+      this._handleInternalEvent(event)
+    );
+  }
+
+  /**
+   * Loads the ad. Not used by {@link NovvyPauseAd} (realtime, no load step).
+   *
+   * Callback-driven: the outcome is delivered via {@link onAdLoaded} /
+   * {@link onAdFailedToLoad}.
+   */
+  load(): void {
+    if (this._isReady || this._disposed) {
+      return;
+    }
+    this._subscribe();
+    try {
+      this._loadNative();
+    } catch (e) {
+      this.onAdFailedToLoad?.(String(e));
+      this.destroy();
+    }
+  }
+
+  /** Releases the ad resources. Idempotent. */
+  destroy(): void {
+    if (this._disposed) {
+      return;
+    }
+    this._disposed = true;
+    this._unsubscribe?.();
+    this._unsubscribe = null;
+    Native.disposeAd(this._adObjectId);
+  }
+
+  // Abstract members
+  protected abstract _loadNative(): void;
+  protected abstract _handleInternalEvent(event: NativeAdEvent): void;
+
+  /**
+   * Shared handling of the common load / fail transitions.
+   * Returns true if the event was consumed here.
+   */
+  protected _handleCommonLoad(event: NativeAdEvent): boolean {
+    switch (event.event) {
+      case NovvyAdEvent.Loaded:
+        this._isReady = true;
+        this.onAdLoaded?.();
+        return true;
+      case NovvyAdEvent.FailedToLoad:
+        this._isReady = false;
+        this.onAdFailedToLoad?.(event.error ?? 'Unknown error');
+        this.destroy();
+        return true;
+      default:
+        return false;
+    }
+  }
+
+  /**
+   * Monotonically increasing per-process counter guaranteeing `adObjectId`
+   * uniqueness even when many ads are constructed within the same millisecond
+   * (e.g. batch-preloading feed items in a synchronous loop). `Date.now()` has
+   * only millisecond resolution, so timestamp + random alone left a real
+   * (~1/10000 per pair) collision window; a colliding id would cross-wire two
+   * ads' event streams. The counter closes that window; the timestamp/random
+   * still disambiguate ids across separate app launches.
+   */
+  private static _counter = 0;
+
+  private static _generateUniqueId(): string {
+    const timestamp = Date.now();
+    const random = Math.floor(Math.random() * 10000);
+    const seq = NovvyAd._counter++;
+    return `ad_${timestamp}_${random}_${seq}`;
+  }
+}

package/src/ads/NovvyEndAd.ts

@@ -0,0 +1,13 @@
+import { NovvyFullScreenAd } from './NovvyFullScreenAd';
+
+/** An end-roll (full-screen) ad, shown after an episode finishes. */
+export class NovvyEndAd extends NovvyFullScreenAd {
+  protected _loadNative(): void {
+    this.native.loadEndAd(this.adUnitId, this.adObjectId);
+  }
+
+  show(): void {
+    this._assertReady();
+    this.native.showEndAd(this.adObjectId);
+  }
+}

package/src/ads/NovvyFullScreenAd.ts

@@ -0,0 +1,46 @@
+import { Native } from '../eventBus';
+import type { NativeAdEvent } from '../spec/NativeNovvyAds';
+import { NovvyAdEvent } from '../types';
+import { NovvyAd } from './NovvyAd';
+
+/**
+ * Base for full-screen ads that follow load → show → dismissed.
+ * Mirrors the Flutter plugin's `_NovvyFullScreenAd`.
+ */
+export abstract class NovvyFullScreenAd extends NovvyAd {
+  /** Called when the ad is displayed. */
+  onAdShowed?: () => void;
+  /** Called when the ad is dismissed (closed) by the user. */
+  onAdDismissed?: () => void;
+
+  /** Shows the ad. Must be called after it has loaded. */
+  abstract show(): void;
+
+  protected _handleInternalEvent(event: NativeAdEvent): void {
+    if (this._handleCommonLoad(event)) {
+      return;
+    }
+    switch (event.event) {
+      case NovvyAdEvent.Showed:
+        this.onAdShowed?.();
+        break;
+      case NovvyAdEvent.Dismissed:
+        this.onAdDismissed?.();
+        this.destroy();
+        break;
+      default:
+        break;
+    }
+  }
+
+  protected _assertReady(): void {
+    if (!this._isReady) {
+      throw new Error('Ad must be loaded before showing.');
+    }
+  }
+
+  /** Uses the module accessor in subclasses. */
+  protected get native() {
+    return Native;
+  }
+}

package/src/ads/NovvyInterstitialAd.ts

@@ -0,0 +1,13 @@
+import { NovvyFullScreenAd } from './NovvyFullScreenAd';
+
+/** An interstitial (full-screen) ad. */
+export class NovvyInterstitialAd extends NovvyFullScreenAd {
+  protected _loadNative(): void {
+    this.native.loadInterstitialAd(this.adUnitId, this.adObjectId);
+  }
+
+  show(): void {
+    this._assertReady();
+    this.native.showInterstitialAd(this.adObjectId);
+  }
+}

package/src/ads/NovvyMidAd.ts

@@ -0,0 +1,13 @@
+import { NovvyFullScreenAd } from './NovvyFullScreenAd';
+
+/** A mid-roll (full-screen) ad, shown at an in-episode break. */
+export class NovvyMidAd extends NovvyFullScreenAd {
+  protected _loadNative(): void {
+    this.native.loadMidAd(this.adUnitId, this.adObjectId);
+  }
+
+  show(): void {
+    this._assertReady();
+    this.native.showMidAd(this.adObjectId);
+  }
+}

package/src/ads/NovvyPauseAd.ts

@@ -0,0 +1,125 @@
+import { Native } from '../eventBus';
+import type { NativeAdEvent } from '../spec/NativeNovvyAds';
+import { NovvyAdEvent, type NovvyPlayerAdapter } from '../types';
+import { NovvyAd } from './NovvyAd';
+
+/** Interval at which player state is pushed to native (mirrors Flutter's 500ms Timer). */
+const PLAYER_PUSH_INTERVAL_MS = 500;
+
+/**
+ * A realtime pause card (fixed 260×90) shown while the player is paused.
+ *
+ * Unlike other ads there is **no** {@link load} step: embedding
+ * `<NovvyPauseAdView>` issues the request immediately via {@link attach}.
+ * Show it the moment playback is paused and {@link destroy} on resume
+ * ({@link onAdHidden}). Mirrors the Flutter plugin's `NovvyPauseAd`.
+ */
+export class NovvyPauseAd extends NovvyAd {
+  /** The Fabric component name used by `<NovvyPauseAdView>`. */
+  static readonly viewType = 'NovvyPauseAdView';
+  /** Pause card width in logical pixels (matches native SDK). */
+  static readonly cardWidth = 260;
+  /** Pause card height in logical pixels (matches native SDK). */
+  static readonly cardHeight = 90;
+
+  /** Called when the pause card is shown. */
+  onAdShowed?: () => void;
+  /** Called when the card is hidden (playback resumed). */
+  onAdHidden?: () => void;
+  /**
+   * Called when the native card's shown state changes, so a view can toggle
+   * touch passthrough / opacity (mirrors Flutter's `shownNotifier`).
+   */
+  onShownChanged?: (shown: boolean) => void;
+
+  private _player: NovvyPlayerAdapter | null = null;
+  private _timer: ReturnType<typeof setInterval> | null = null;
+
+  protected _loadNative(): never {
+    throw new Error('NovvyPauseAd has no load step; use attach().');
+  }
+
+  /**
+   * Attach the pause ad and issue the request in realtime.
+   *
+   * The player's current state is read once and sent with the request; a
+   * 500ms timer then keeps pushing state so the SDK can detect resumption.
+   */
+  attach(player: NovvyPlayerAdapter): void {
+    if (this._disposed) {
+      return;
+    }
+    this._player = player;
+    this._subscribe();
+    Native.attachPauseAd(
+      this.adUnitId,
+      this.adObjectId,
+      player.currentPositionMs,
+      player.isPlaying
+    );
+    this._startPlayerTimer();
+  }
+
+  /** Detach the pause ad and stop pushing player state. */
+  detach(): void {
+    this._stopPlayerTimer();
+    this._player = null;
+    Native.detachPauseAd(this.adObjectId);
+  }
+
+  destroy(): void {
+    if (this._disposed) {
+      return;
+    }
+    this._stopPlayerTimer();
+    this._player = null;
+    super.destroy();
+  }
+
+  private _startPlayerTimer(): void {
+    this._stopPlayerTimer();
+    this._timer = setInterval(() => {
+      const player = this._player;
+      if (!player) {
+        return;
+      }
+      Native.updatePauseAdPlayerState(
+        this.adObjectId,
+        player.currentPositionMs,
+        player.isPlaying
+      );
+    }, PLAYER_PUSH_INTERVAL_MS);
+  }
+
+  private _stopPlayerTimer(): void {
+    if (this._timer) {
+      clearInterval(this._timer);
+      this._timer = null;
+    }
+  }
+
+  protected _handleInternalEvent(event: NativeAdEvent): void {
+    switch (event.event) {
+      case NovvyAdEvent.FailedToLoad:
+        this.onAdFailedToLoad?.(event.error ?? 'Unknown error');
+        // Stops the player timer + unsubscribes before releasing native —
+        // avoids a leaked 500ms push loop on failure.
+        this.destroy();
+        break;
+      case NovvyAdEvent.Showed:
+        if (!this._disposed) {
+          this.onShownChanged?.(true);
+        }
+        this.onAdShowed?.();
+        break;
+      case NovvyAdEvent.Hidden:
+        if (!this._disposed) {
+          this.onShownChanged?.(false);
+        }
+        this.onAdHidden?.();
+        break;
+      default:
+        break;
+    }
+  }
+}

package/src/ads/NovvyRewardedAd.ts

@@ -0,0 +1,49 @@
+import { Native } from '../eventBus';
+import type { NativeAdEvent } from '../spec/NativeNovvyAds';
+import { NovvyAdEvent } from '../types';
+import { NovvyAd } from './NovvyAd';
+
+/** A rewarded video ad. */
+export class NovvyRewardedAd extends NovvyAd {
+  /** Called when the ad is displayed. */
+  onAdShowed?: () => void;
+  /** Called when the ad is dismissed by the user. */
+  onAdDismissed?: () => void;
+  /**
+   * Called once when the user earns the reward. No reward payload — the native
+   * SDKs deliver a parameterless signal (grant the host's own reward).
+   */
+  onUserEarnedReward?: () => void;
+
+  protected _loadNative(): void {
+    Native.loadRewardedAd(this.adUnitId, this.adObjectId);
+  }
+
+  /** Shows the rewarded video ad. Must be called after it has loaded. */
+  show(): void {
+    if (!this._isReady) {
+      throw new Error('Ad must be loaded before showing.');
+    }
+    Native.showRewardedAd(this.adObjectId);
+  }
+
+  protected _handleInternalEvent(event: NativeAdEvent): void {
+    if (this._handleCommonLoad(event)) {
+      return;
+    }
+    switch (event.event) {
+      case NovvyAdEvent.Showed:
+        this.onAdShowed?.();
+        break;
+      case NovvyAdEvent.EarnedReward:
+        this.onUserEarnedReward?.();
+        break;
+      case NovvyAdEvent.Dismissed:
+        this.onAdDismissed?.();
+        this.destroy();
+        break;
+      default:
+        break;
+    }
+  }
+}

package/src/ads/NovvyScrollAd.ts

@@ -0,0 +1,138 @@
+import { Native } from '../eventBus';
+import type { NativeAdEvent } from '../spec/NativeNovvyAds';
+import { NovvyAdEvent } from '../types';
+import { NovvyAd } from './NovvyAd';
+
+/**
+ * A scroll ad that renders as a native view inserted into a scrollable list.
+ *
+ * Lifecycle: {@link load} → embed `<NovvyScrollAdView>` → {@link setPlaying} as
+ * it enters / leaves the viewport → {@link destroy}. Attach/detach are driven
+ * by the `<NovvyScrollAdView>` component's mount lifecycle.
+ */
+export class NovvyScrollAd extends NovvyAd {
+  /** The Fabric component name used by `<NovvyScrollAdView>`. */
+  static readonly viewType = 'NovvyScrollAdView';
+
+  /**
+   * Optional override for the episode number used in the bid request. When
+   * non-null, takes precedence over the value set via
+   * {@link NovvyAds.setContentContext}.
+   */
+  readonly episodeNumber?: number | null;
+
+  /** Called when the ad becomes visible in the viewport. */
+  onAdShowed?: () => void;
+  /** Called when the ad is hidden / removed from the viewport. */
+  onAdHidden?: () => void;
+  /**
+   * Called every second during playback with the remaining seconds
+   * (0 = user can swipe past the ad).
+   */
+  onAdPlaybackTick?: (remainingSeconds: number) => void;
+
+  constructor(adUnitId: string, episodeNumber?: number | null) {
+    super(adUnitId);
+    this.episodeNumber = episodeNumber;
+  }
+
+  // ── Attach coordination ────────────────────────────────────────────────
+  //
+  // The native SCROLL contract is strictly two-stage: `load()` must resolve the
+  // creative BEFORE `attach()` — the native engine drops an early attach with a
+  // "not ready" log and never retries (see NovvyPlacementAd.attach). But the two
+  // triggers here are independent: `load()` is host-driven and network-bound,
+  // while the native container becomes available on the view's `onViewReady`
+  // (local, fast). View-ready therefore almost always beats `loaded`, so a naive
+  // "attach on view-ready" fires too early, silently no-ops, and the slot stays
+  // on its black placeholder for every creative type.
+  //
+  // We instead attach only once BOTH signals have arrived (whichever is last),
+  // and buffer the host's play intent so it survives being set before attach and
+  // is re-applied across detach/re-attach (scroll off- and back on-screen).
+  private _viewReady = false;
+  private _attached = false;
+  /** Last play intent from the host; (re)applied on each attach. */
+  private _playing = false;
+  private _durationSeconds: number | null = null;
+  private _useDefaultSwipeOverlay = true;
+
+  protected _loadNative(): void {
+    Native.loadScrollAd(this.adUnitId, this.adObjectId, this.episodeNumber ?? null);
+  }
+
+  /**
+   * Signals that the native container is ready (fired automatically by
+   * `<NovvyScrollAdView>` on `onViewReady`). Records the attach params and
+   * mounts the ad once it has also finished loading.
+   */
+  attach(durationSeconds?: number | null, useDefaultSwipeOverlay = true): void {
+    this._durationSeconds = durationSeconds ?? null;
+    this._useDefaultSwipeOverlay = useDefaultSwipeOverlay;
+    this._viewReady = true;
+    this._maybeAttach();
+  }
+
+  /** Detach the scroll ad from its container. */
+  detach(): void {
+    this._viewReady = false;
+    this._attached = false;
+    Native.detachScrollAd(this.adObjectId);
+  }
+
+  /**
+   * Set the playing state. Call `setPlaying(true)` when the item scrolls into
+   * the viewport and `setPlaying(false)` when it scrolls out. Safe to call
+   * before the ad has attached — the intent is buffered and applied on attach.
+   */
+  setPlaying(playing: boolean): void {
+    this._playing = playing;
+    if (this._attached) {
+      Native.setScrollAdPlaying(this.adObjectId, playing);
+    }
+  }
+
+  /**
+   * Attach once the ad is loaded AND the native view is ready — the native
+   * engine requires load-before-attach and does not retry, so we gate on both.
+   */
+  private _maybeAttach(): void {
+    if (this._attached || this._disposed || !this._isReady || !this._viewReady) {
+      return;
+    }
+    Native.attachScrollAd(
+      this.adObjectId,
+      this._durationSeconds,
+      this._useDefaultSwipeOverlay
+    );
+    this._attached = true;
+    // Re-apply the buffered play intent now that a native host exists.
+    if (this._playing) {
+      Native.setScrollAdPlaying(this.adObjectId, true);
+    }
+  }
+
+  protected _handleInternalEvent(event: NativeAdEvent): void {
+    if (this._handleCommonLoad(event)) {
+      // `loaded` may arrive after the view is already ready; attach now that
+      // the native engine has the creative (after any onAdLoaded → setPlaying).
+      if (event.event === NovvyAdEvent.Loaded) {
+        this._maybeAttach();
+      }
+      return;
+    }
+    switch (event.event) {
+      case NovvyAdEvent.Showed:
+        this.onAdShowed?.();
+        break;
+      case NovvyAdEvent.Hidden:
+        this.onAdHidden?.();
+        break;
+      case NovvyAdEvent.PlaybackTick:
+        this.onAdPlaybackTick?.(event.remainingSeconds ?? 0);
+        break;
+      default:
+        break;
+    }
+  }
+}

package/src/eventBus.ts

@@ -0,0 +1,59 @@
+import NovvyAdsNative from './spec/NativeNovvyAds';
+import type { NativeAdEvent } from './spec/NativeNovvyAds';
+
+/**
+ * Central hub over the single native→JS `onAdEvent` stream.
+ *
+ * Mirrors the Flutter plugin's `_NovvyAdsImpl` broadcast stream: one native
+ * event source is fanned out to per-ad handlers filtered by `adObjectId`.
+ */
+
+export type AdEventHandler = (event: NativeAdEvent) => void;
+
+const handlers = new Map<string, Set<AdEventHandler>>();
+let subscription: { remove(): void } | null = null;
+
+function ensureSubscribed(): void {
+  if (subscription) {
+    return;
+  }
+  subscription = NovvyAdsNative.onAdEvent((event: NativeAdEvent) => {
+    const set = handlers.get(event.adObjectId);
+    if (!set) {
+      return;
+    }
+    // Copy so a handler may unsubscribe/destroy during dispatch.
+    for (const handler of Array.from(set)) {
+      handler(event);
+    }
+  });
+}
+
+/**
+ * Subscribe to events for a single ad instance. Returns an unsubscribe fn.
+ */
+export function subscribe(
+  adObjectId: string,
+  handler: AdEventHandler
+): () => void {
+  ensureSubscribed();
+  let set = handlers.get(adObjectId);
+  if (!set) {
+    set = new Set();
+    handlers.set(adObjectId, set);
+  }
+  set.add(handler);
+  return () => {
+    const current = handlers.get(adObjectId);
+    if (!current) {
+      return;
+    }
+    current.delete(handler);
+    if (current.size === 0) {
+      handlers.delete(adObjectId);
+    }
+  };
+}
+
+/** The underlying TurboModule instance. */
+export const Native = NovvyAdsNative;