@chipmobilesdk/rn-ads 0.6.0 → 0.8.0

package/lib/module/testing/index.js

@@ -0,0 +1,366 @@
+"use strict";
+
+/**
+ * Deterministic in-memory ads engine for tests (SC-012).
+ *
+ * This is a real implementation of the same `AdsEngine` port the AdMob adapter
+ * implements, not a parallel mock — so a contract change breaks it at compile
+ * time and it cannot drift. Nothing here touches a native module or a network.
+ *
+ * It exists to make the package's guarantees provable. The recorded call log is
+ * what SC-002 asserts against ("zero production identifiers reached the
+ * adapter") and what SC-003 asserts against ("zero calls before consent").
+ * Callback emission is fully caller-driven, which is what lets a test run the
+ * reward-before-dismiss and dismiss-before-reward orderings and demand the same
+ * outcome from both (SC-007).
+ *
+ * Exported from `@chipmobilesdk/rn-ads/testing`, never from the main entrypoint,
+ * so test doubles cannot reach a production bundle.
+ */
+
+import React from 'react';
+import { View } from 'react-native';
+export { createTestClock } from "./clock.js";
+import { createTestClock } from "./clock.js";
+import { testAdUnitFor } from "../engine/testAdUnits.js";
+
+/**
+ * A privacy options form the test is holding open (0.4.0).
+ *
+ * Settle it whenever the test chooses, which is what lets `busy`, a second
+ * call, a consent update, and `dispose()` all be exercised *while* the form is
+ * on screen — in any order, rather than only the one a resolved promise allows.
+ */
+
+const DEFAULT_CONSENT = {
+  status: 'not_required',
+  canRequestAds: true,
+  isFormAvailable: false,
+  privacyOptions: 'not_required'
+};
+/**
+ * Runs `task` on the next microtask, which is when a provider's callbacks would
+ * arrive. Written out because React Native's type declarations omit
+ * `queueMicrotask`, although Hermes has it.
+ */
+function nextMicrotask(task) {
+  Promise.resolve().then(task);
+}
+
+/** The testID the fake banner renders under, for a test to find it by. */
+export const FAKE_BANNER_TEST_ID = 'ads-fake-banner';
+
+/**
+ * The fake engine's banner component.
+ *
+ * It renders a host view carrying the props the package handed it, so a test
+ * can read them and call the callbacks: `getByTestId(FAKE_BANNER_TEST_ID)`.
+ * It used to render `null`, which left the props reachable only on the
+ * component instance — something `@testing-library/react-native` cannot see,
+ * since a host element is all a consumer's own tests can query.
+ */
+function FakeBanner(props) {
+  return /*#__PURE__*/React.createElement(View, {
+    ...props,
+    testID: FAKE_BANNER_TEST_ID
+  });
+}
+export function createFakeAdsEngine(options = {}) {
+  const calls = [];
+  const consentCalls = [];
+  const clock = options.clock ?? createTestClock();
+  let consentInfo = {
+    ...DEFAULT_CONSENT,
+    ...options.consentInfo
+  };
+  let consentRequestFailure;
+  let consentFormFailure;
+  let privacyFormFailure;
+  let privacyFormResult = {};
+  let consentReadFailure;
+  /** Set by `holdPrivacyOptionsForm`; consumed by the next form. */
+  let heldForm = null;
+  const consent = {
+    async requestInfoUpdate(consentOptions) {
+      consentCalls.push({
+        kind: 'requestInfoUpdate',
+        options: consentOptions
+      });
+      if (consentRequestFailure !== undefined) {
+        throw consentRequestFailure;
+      }
+      return consentInfo;
+    },
+    async showFormIfRequired() {
+      consentCalls.push({
+        kind: 'showFormIfRequired'
+      });
+      if (consentFormFailure !== undefined) {
+        throw consentFormFailure;
+      }
+      // A presented form that the user completes moves the status on. The
+      // fake only does this when a form was actually required, mirroring the
+      // provider: showing nothing cannot change an answer.
+      // A region that required a form is one that requires a way back into
+      // it, which is what the provider reports once consent is obtained.
+      if (consentInfo.status === 'required' && consentInfo.isFormAvailable) {
+        consentInfo = {
+          status: 'obtained',
+          canRequestAds: true,
+          isFormAvailable: false,
+          privacyOptions: 'required'
+        };
+      }
+      return consentInfo;
+    },
+    async showPrivacyOptionsForm() {
+      consentCalls.push({
+        kind: 'showPrivacyOptionsForm'
+      });
+      const held = heldForm;
+      heldForm = null;
+      if (held) {
+        // Rejects if the test calls `fail`, which is exactly the provider's
+        // failure path; resolves with what the user left behind otherwise.
+        consentInfo = {
+          ...consentInfo,
+          ...(await held)
+        };
+        return consentInfo;
+      }
+      if (privacyFormFailure !== undefined) {
+        throw privacyFormFailure;
+      }
+      consentInfo = {
+        ...consentInfo,
+        ...privacyFormResult
+      };
+      return consentInfo;
+    },
+    async getInfo() {
+      consentCalls.push({
+        kind: 'getInfo'
+      });
+      if (consentReadFailure !== undefined) {
+        throw consentReadFailure;
+      }
+      return consentInfo;
+    },
+    reset() {
+      consentCalls.push({
+        kind: 'reset'
+      });
+      consentInfo = {
+        status: 'unknown',
+        canRequestAds: false,
+        isFormAvailable: true,
+        privacyOptions: 'unknown'
+      };
+    }
+  };
+  const listeners = new Map();
+  /** Callbacks queued before anyone subscribed; see `subscribe`. */
+  const pending = new Map();
+  const live = new Set();
+  let counter = 0;
+  function record(call) {
+    calls.push(call);
+  }
+  return {
+    calls,
+    consentCalls,
+    consent,
+    clock,
+    advance(ms) {
+      clock.advance(ms);
+    },
+    setConsentInfo(info) {
+      consentInfo = {
+        ...consentInfo,
+        ...info
+      };
+    },
+    failConsentRequest(cause = new Error('consent request failed')) {
+      consentRequestFailure = cause;
+    },
+    failConsentForm(cause = new Error('consent form failed')) {
+      consentFormFailure = cause;
+    },
+    setPrivacyOptionsFormResult(info) {
+      privacyFormResult = info;
+    },
+    failPrivacyOptionsForm(cause = new Error('privacy options form failed')) {
+      privacyFormFailure = cause;
+    },
+    holdPrivacyOptionsForm() {
+      let settle;
+      const promise = new Promise((resolve, reject) => {
+        settle = {
+          resolve,
+          reject
+        };
+      });
+      heldForm = promise;
+      return {
+        close(info = {}) {
+          settle.resolve(info);
+        },
+        fail(cause = new Error('privacy options form failed')) {
+          settle.reject(cause);
+        }
+      };
+    },
+    failConsentInfoRead(cause = new Error('consent information read failed')) {
+      consentReadFailure = cause;
+    },
+    isAvailable() {
+      return options.available !== false;
+    },
+    // Renders nothing. A test finds it in the tree by its `adUnitId` prop and
+    // calls `onLoaded`, `onFailed`, `onImpression` or `onClicked` itself, which
+    // is how a banner is driven without mocking a native module (ADS-12).
+    banner: {
+      isAvailable: () => options.available !== false,
+      Component: FakeBanner
+    },
+    async initialize(privacy) {
+      record({
+        kind: 'initialize',
+        privacy
+      });
+      if (options.failInitialize !== undefined) {
+        throw options.failInitialize;
+      }
+    },
+    async createFullScreen(format, adUnitId, request) {
+      counter += 1;
+      const id = `fake-${counter}`;
+      record({
+        kind: 'createFullScreen',
+        format,
+        adUnitId,
+        handleId: id,
+        request
+      });
+      live.add(id);
+      // A real provider delivers `loaded` to a listener attached after the
+      // ad object exists, so the callback is queued here and flushed when
+      // the caller subscribes. Emitting eagerly would race the caller's own
+      // subscribe and the event would be dropped — which is a property of
+      // this fake, not of the package, and would make the load look hung.
+      if (!options.neverCallBack) {
+        pending.set(id, {
+          type: 'loaded'
+        });
+      }
+      return {
+        id
+      };
+    },
+    async show(handle) {
+      record({
+        kind: 'show',
+        handleId: handle.id
+      });
+      if (options.failShow !== undefined) {
+        throw options.failShow;
+      }
+      if (!options.neverCallBack) {
+        // `show` is called with a listener already attached, so this one
+        // can go out directly on the next microtask.
+        nextMicrotask(() => {
+          for (const listener of Array.from(listeners.get(handle.id) ?? [])) {
+            listener({
+              type: 'opened'
+            });
+          }
+        });
+      }
+    },
+    subscribe(handle, listener) {
+      let set = listeners.get(handle.id);
+      if (!set) {
+        set = new Set();
+        listeners.set(handle.id, set);
+      }
+      set.add(listener);
+      // Flush whatever the provider would have delivered between creating
+      // the ad and this subscription.
+      const queued = pending.get(handle.id);
+      if (queued) {
+        pending.delete(handle.id);
+        nextMicrotask(() => {
+          for (const target of Array.from(listeners.get(handle.id) ?? [])) {
+            target(queued);
+          }
+        });
+      }
+      let active = true;
+      return () => {
+        if (!active) {
+          return;
+        }
+        active = false;
+        set?.delete(listener);
+        if (set && set.size === 0) {
+          listeners.delete(handle.id);
+        }
+      };
+    },
+    dispose(handle) {
+      record({
+        kind: 'dispose',
+        handleId: handle.id
+      });
+      live.delete(handle.id);
+      listeners.delete(handle.id);
+      pending.delete(handle.id);
+    },
+    adUnitIds() {
+      return calls.filter(call => call.kind === 'createFullScreen').map(call => call.adUnitId);
+    },
+    liveHandles() {
+      return Array.from(live);
+    },
+    emit(handleId, event) {
+      for (const listener of Array.from(listeners.get(handleId) ?? [])) {
+        listener(event);
+      }
+    },
+    completeLoad(handleId) {
+      this.emit(handleId, {
+        type: 'loaded'
+      });
+    },
+    emitReward(handleId, reward = {
+      type: 'coins',
+      amount: 10
+    }) {
+      this.emit(handleId, {
+        type: 'rewarded',
+        reward
+      });
+    },
+    listenerCount() {
+      let total = 0;
+      for (const set of listeners.values()) {
+        total += set.size;
+      }
+      return total;
+    },
+    reset() {
+      calls.length = 0;
+    }
+  };
+}
+export { adsEngineChecks, runAdsEngineConformance } from "./conformance.js";
+/** Google's official test ad unit for each format, as the package substitutes them (FR-011). */
+export function allTestAdUnits() {
+  return {
+    banner: testAdUnitFor('banner'),
+    interstitial: testAdUnitFor('interstitial'),
+    rewarded: testAdUnitFor('rewarded'),
+    app_open: testAdUnitFor('app_open')
+  };
+}
+//# sourceMappingURL=index.js.map

package/lib/module/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["React","View","createTestClock","testAdUnitFor","DEFAULT_CONSENT","status","canRequestAds","isFormAvailable","privacyOptions","nextMicrotask","task","Promise","resolve","then","FAKE_BANNER_TEST_ID","FakeBanner","props","createElement","testID","createFakeAdsEngine","options","calls","consentCalls","clock","consentInfo","consentRequestFailure","consentFormFailure","privacyFormFailure","privacyFormResult","consentReadFailure","heldForm","consent","requestInfoUpdate","consentOptions","push","kind","undefined","showFormIfRequired","showPrivacyOptionsForm","held","getInfo","reset","listeners","Map","pending","live","Set","counter","record","call","advance","ms","setConsentInfo","info","failConsentRequest","cause","Error","failConsentForm","setPrivacyOptionsFormResult","failPrivacyOptionsForm","holdPrivacyOptionsForm","settle","promise","reject","close","fail","failConsentInfoRead","isAvailable","available","banner","Component","initialize","privacy","failInitialize","createFullScreen","format","adUnitId","request","id","handleId","add","neverCallBack","set","type","show","handle","failShow","listener","Array","from","get","subscribe","queued","delete","target","active","size","dispose","adUnitIds","filter","map","liveHandles","emit","event","completeLoad","emitReward","reward","amount","listenerCount","total","values","length","adsEngineChecks","runAdsEngineConformance","allTestAdUnits","interstitial","rewarded","app_open"],"sourceRoot":"../../../src","sources":["testing/index.ts"],"mappings":"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","ignoreList":[]}

package/lib/typescript/commonjs/config/resolveAdUnit.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The production-traffic guarantee (FR-011, FR-011a).
+ *
+ * A pure function, deliberately. This is the single point where a production ad
+ * unit can be replaced by an official test one, which is what makes SC-002
+ * provable rather than merely intended: a guarantee enforced in one place can be
+ * asserted; one spread across three call sites is a hope.
+ *
+ * The rule, from the 2026-09-02 clarification session:
+ *
+ *   production            -> use what the app configured, always, no exceptions
+ *   development / test    -> if it is not one of our own official test units,
+ *                            replace it and say so, loudly, naming the key
+ *
+ * Substitution rather than rejection is a deliberate trade. Rejecting would
+ * block a developer whose only mistake was pulling a teammate's environment
+ * file, and turn a configuration smell into a broken integration at every
+ * startup. Substituting keeps the app working — which is what a non-production
+ * build is for — and reports the problem as a first-class signal. The accepted
+ * cost is that a warning can be ignored; it is bounded because production never
+ * substitutes, so the misconfiguration surfaces there as ordinary behavior
+ * rather than as hidden state.
+ */
+import type { Environment, PlacementDefinition } from './types';
+export interface ResolvedAdUnit {
+    readonly effectiveAdUnitId: string;
+    /** True when the configured identifier was replaced. Drives FR-011a's warning. */
+    readonly substituted: boolean;
+}
+export declare function resolveAdUnit(placement: PlacementDefinition, environment: Environment): ResolvedAdUnit;
+export interface ResolvedCatalog {
+    /** Placement key to the ad unit that will actually be requested. */
+    readonly byKey: ReadonlyMap<string, string>;
+    /** Every key whose identifier was replaced, in catalog order (FR-011a). */
+    readonly substitutedKeys: readonly string[];
+}
+/**
+ * Resolves a whole catalog at once, so the warning can name every affected
+ * placement in a single event rather than trickling one out per load — an
+ * integrator wants to fix the whole file, not discover it a placement at a time.
+ */
+export declare function resolvePlacementAdUnits(placements: readonly PlacementDefinition[], environment: Environment): ResolvedCatalog;
+//# sourceMappingURL=resolveAdUnit.d.ts.map

package/lib/typescript/commonjs/config/resolveAdUnit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveAdUnit.d.ts","sourceRoot":"","sources":["../../../../src/config/resolveAdUnit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAGhE,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC9B;AAED,wBAAgB,aAAa,CAC5B,SAAS,EAAE,mBAAmB,EAC9B,WAAW,EAAE,WAAW,GACtB,cAAc,CAkBhB;AAED,MAAM,WAAW,eAAe;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACtC,UAAU,EAAE,SAAS,mBAAmB,EAAE,EAC1C,WAAW,EAAE,WAAW,GACtB,eAAe,CAajB"}