@chipmobilesdk/rn-ads 0.6.0 → 0.8.0

package/lib/typescript/commonjs/engine/testAdUnits.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Google's official test ad units (FR-013).
+ *
+ * PRIVATE. Never exported from `src/index.ts`.
+ *
+ * FR-013 forbids the package from carrying production identifiers, credentials,
+ * or host-app rules, and explicitly permits official test identifiers provided
+ * they are documented as such — this file is that documentation.
+ *
+ * They are hard-coded rather than read from configuration on purpose: FR-011's
+ * substitution guarantee must hold even when the app's configuration is the
+ * thing that is wrong, so it cannot depend on the app supplying anything. They
+ * are also not re-exported from the provider bridge's own `TestIds`, because
+ * that would put a provider symbol on this package's dependency path for a
+ * value that is really just four documented constants (FR-002).
+ *
+ * Source: Google Mobile Ads "Test ads" documentation, cross-checked against the
+ * bridge's `src/TestIds.ts` at version 16.0.3. These identifiers are public,
+ * are the same for every publisher, and always fill.
+ */
+import type { AdFormat } from '../config/types';
+export declare function testAdUnitFor(format: AdFormat): string;
+/**
+ * Whether an identifier is one of ours.
+ *
+ * This is the structural test that drives substitution: anything that is not a
+ * known official test unit is treated as production-owned. Deliberately not a
+ * parse of AdMob's publisher-id format — a rule like that becomes wrong the day
+ * Google changes the format, and being wrong here means either sending a
+ * production request or blocking a legitimate one.
+ */
+export declare function isOfficialTestAdUnit(adUnitId: string): boolean;
+//# sourceMappingURL=testAdUnits.d.ts.map

package/lib/typescript/commonjs/engine/testAdUnits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testAdUnits.d.ts","sourceRoot":"","sources":["../../../../src/engine/testAdUnits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAchD,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,CAEtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAO9D"}

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

@@ -0,0 +1,42 @@
+/**
+ * @chipmobilesdk/rn-ads — reusable advertising capability for
+ * ChipMobileSdk-family React Native apps.
+ *
+ * This is the public entrypoint (LIB-003). Modules under `config/`, `core/`,
+ * `engine/`, `react/`, and `diagnostics/` are private; import them only through
+ * this file. The fake engine lives behind `@chipmobilesdk/rn-ads/testing` so
+ * test doubles cannot reach a production bundle.
+ *
+ * Nothing exported here names Google, AdMob, or any provider type (FR-002).
+ * `src/__tests__/public-api.test.ts` asserts that mechanically.
+ *
+ * The package owns capability: a safe, consistent way to request and present
+ * ads. The consuming app owns policy — where ads appear, when, how often, under
+ * what consent, and whether they appear at all. There is no placement rule, no
+ * frequency cap, and no screen name in this package (FR-045).
+ */
+import type { AdsConfig } from './config/types';
+import { type AdsInstance, type CreateAdsOptions } from './core/adsInstance';
+export type { AdContentRating, AdFormat, AdsConfig, ConsentSnapshot, ConsentState, ConsentTestingOptions, Enablement, Environment, FullScreenFormat, InitStatus, PlacementDefinition, PlacementState, PrivacyBlockReason, PrivacyOptions, PrivacyOptionsRequirement, RetryPolicy, Reward, TimeoutConfig, UnavailableReason, Unsubscribe, } from './config/types';
+export { isFullScreenFormat } from './config/types';
+export { AD_VALIDITY_BOUNDS, APP_OPEN_VALIDITY_BOUNDS, DEFAULT_AD_VALIDITY_MS, DEFAULT_APP_OPEN_VALIDITY_MS, DEFAULT_LOAD_TIMEOUT_MS, DEFAULT_RETRY_POLICY, DEFAULT_SHOW_TIMEOUT_MS, DEFAULT_UNDECIDED_WARNING_MS, LOAD_TIMEOUT_BOUNDS, RETRY_BOUNDS, SHOW_TIMEOUT_BOUNDS, UNDECIDED_WARNING_BOUNDS, } from './core/timers';
+export { DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS, DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS, MIN_REQUEST_INTERVAL_BOUNDS, defaultMinRequestIntervalMs, } from './core/requestThrottle';
+export type { EnablementResult } from './core/enablement';
+/**
+ * Creates an ads instance. This is the composition root: core's instance with
+ * the AdMob adapter as its default engine, so core/ itself never loads an
+ * adapter (ADS-14). The adapter resolves the provider bridge only on first use,
+ * so importing the package where there is no adapter, or no bridge, costs
+ * nothing and crashes nothing (FR-025, SC-004).
+ */
+export declare function createAds(config: AdsConfig, options?: CreateAdsOptions): AdsInstance;
+export type { AdsInstance, ConsentApi, InitResult, LoadResult, PrivacyOptionsFormResult, PrivacyUpdateResult, ShowResult, } from './core/adsInstance';
+export { AdsBanner } from './react/AdsBanner';
+export type { AdsBannerProps } from './react/AdsBanner';
+export { AdsProvider, useAds } from './react/AdsProvider';
+export type { AdsProviderProps } from './react/AdsProvider';
+export { useAdsEvents, useAdsStatus, usePlacementState } from './react/hooks';
+export { AdsConfigError, AdsError, isAdsError } from './diagnostics/errors';
+export type { AdsErrorCode, AdsOperation } from './diagnostics/errors';
+export type { AdEvent, AdEventListener, AdEventType, ConfigWarning, ImpressionSource, } from './diagnostics/events';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAEN,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,MAAM,oBAAoB,CAAC;AAI5B,YAAY,EACX,eAAe,EACf,QAAQ,EACR,SAAS,EACT,eAAe,EACf,YAAY,EACZ,qBAAqB,EACrB,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,mBAAmB,EACnB,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,yBAAyB,EACzB,WAAW,EACX,MAAM,EACN,aAAa,EACb,iBAAiB,EACjB,WAAW,GACX,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAIpD,OAAO,EACN,kBAAkB,EAClB,wBAAwB,EACxB,sBAAsB,EACtB,4BAA4B,EAC5B,uBAAuB,EACvB,oBAAoB,EACpB,uBAAuB,EACvB,4BAA4B,EAC5B,mBAAmB,EACnB,YAAY,EACZ,mBAAmB,EACnB,wBAAwB,GACxB,MAAM,eAAe,CAAC;AAKvB,OAAO,EACN,sCAAsC,EACtC,2CAA2C,EAC3C,2BAA2B,EAC3B,2BAA2B,GAC3B,MAAM,wBAAwB,CAAC;AAIhC,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAI1D;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,GAAE,gBAAqB,GAAG,WAAW,CAExF;AACD,YAAY,EACX,WAAW,EACX,UAAU,EACV,UAAU,EACV,UAAU,EACV,wBAAwB,EACxB,mBAAmB,EACnB,UAAU,GACV,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAG9E,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAC5E,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACvE,YAAY,EACX,OAAO,EACP,eAAe,EACf,WAAW,EACX,aAAa,EACb,gBAAgB,GAChB,MAAM,sBAAsB,CAAC"}

package/lib/typescript/commonjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/lib/typescript/commonjs/react/AdsBanner.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Adaptive banner host (FR-038 – FR-042).
+ *
+ * The app puts this where it wants a banner. The component never inserts itself
+ * into the tree, never overlays app content, and ships no placeholder — the
+ * surrounding layout, and any loading or fallback presentation, belong to the
+ * app and its theme (FR-040, UX-001).
+ *
+ * When ads are disabled or unavailable it renders `null` rather than a
+ * zero-height view. That is not a micro-optimization: a rendered empty view
+ * still sits in the accessibility tree and can take screen-reader focus ahead of
+ * real content. `null` leaves the tree entirely (UX-003).
+ *
+ * The provider owns the banner's whole lifecycle through its own component, so
+ * this adapts those callbacks into the normalized event model instead of routing
+ * a banner through the load/show handle model, which does not fit it.
+ */
+import React from 'react';
+import { type ViewStyle } from 'react-native';
+import type { PlacementState } from '../config/types';
+export interface AdsBannerProps {
+    readonly placementKey: string;
+    /** Called on every state change so the app can hold or reclaim the space. */
+    readonly onStateChange?: (state: PlacementState) => void;
+    /** Applied to the container only. Never to ad content, which is not ours. */
+    readonly style?: ViewStyle;
+}
+export declare function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps): React.JSX.Element | null;
+//# sourceMappingURL=AdsBanner.d.ts.map

package/lib/typescript/commonjs/react/AdsBanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdsBanner.d.ts","sourceRoot":"","sources":["../../../../src/react/AdsBanner.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAmE,MAAM,OAAO,CAAC;AACxF,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAE5E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAQtD,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IACzD,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;CAC3B;AAED,wBAAgB,SAAS,CAAC,EAAE,YAAY,EAAE,aAAa,EAAE,KAAK,EAAE,EAAE,cAAc,4BA0T/E"}

package/lib/typescript/commonjs/react/AdsProvider.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Instance context (US1).
+ *
+ * Supplies one `AdsInstance` to the tree so `AdsBanner` and the hooks can reach
+ * it without every screen threading it through props.
+ *
+ * The provider does not create the instance. The app does, and passes it in —
+ * because `createAds` throws on a misconfigured catalog (FR-008, FR-012), and a
+ * throw during render is a far worse place to discover that than a throw at
+ * startup where the app can decide what to do about it.
+ */
+import React, { type ReactNode } from 'react';
+import type { AdsInstance } from '../core/adsInstance';
+export interface AdsProviderProps {
+    readonly instance: AdsInstance;
+    /**
+     * Whether the provider forwards foreground/background transitions to the
+     * instance. On by default: FR-034's "never show while inactive" and
+     * "re-evaluate a stale ad on return" both depend on the instance being told.
+     * Turn it off only when the app already drives `setAppActive` itself. The
+     * transitions come from rn-core's shared `appLifecycle()`; `inactive` counts as
+     * not active.
+     */
+    readonly trackAppState?: boolean;
+    readonly children: ReactNode;
+}
+export declare function AdsProvider({ instance, trackAppState, children }: AdsProviderProps): React.JSX.Element;
+/**
+ * Returns the instance, or null outside a provider.
+ *
+ * Null rather than a throw on purpose: a screen that renders a banner should
+ * degrade to rendering nothing when ads are not wired up, not take the screen
+ * down with it (NFR-005).
+ */
+export declare function useAds(): AdsInstance | null;
+//# sourceMappingURL=AdsProvider.d.ts.map

package/lib/typescript/commonjs/react/AdsProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdsProvider.d.ts","sourceRoot":"","sources":["../../../../src/react/AdsProvider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,EAAwC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAEpF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIvD,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;CAC7B;AAED,wBAAgB,WAAW,CAAC,EAAE,QAAQ,EAAE,aAAoB,EAAE,QAAQ,EAAE,EAAE,gBAAgB,qBAWzF;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,IAAI,WAAW,GAAG,IAAI,CAE3C"}

package/lib/typescript/commonjs/react/hooks.d.ts

@@ -0,0 +1,27 @@
+/**
+ * React bindings (US1, FR-027).
+ *
+ * Each hook subscribes to exactly what it reads. `usePlacementState` subscribes
+ * to one placement rather than to the whole event stream, which is what keeps a
+ * banner from re-rendering because an unrelated interstitial was clicked —
+ * PERF-002's bounded re-render assertion depends on it.
+ *
+ * None of these hand back an ad object. A consumer queries and subscribes to
+ * state; it never holds provider-owned memory (FR-027).
+ */
+import type { InitStatus, PlacementState } from '../config/types';
+import type { AdEventListener } from '../diagnostics/events';
+/** Live state for one placement. `unavailable` outside a provider. */
+export declare function usePlacementState(placementKey: string): PlacementState;
+/** Live initialization status. `unavailable` outside a provider. */
+export declare function useAdsStatus(): InitStatus;
+/**
+ * Forwards every event to a listener without causing a render.
+ *
+ * Deliberately does not accumulate events into state: a package that kept an
+ * event log would be persisting exactly the kind of history it promises not to
+ * (FR-021), and re-rendering on every impression would defeat PERF-002. A screen
+ * that wants a visible log keeps its own.
+ */
+export declare function useAdsEvents(listener: AdEventListener): void;
+//# sourceMappingURL=hooks.d.ts.map

package/lib/typescript/commonjs/react/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../../src/react/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAG7D,sEAAsE;AACtE,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,cAAc,CActE;AAED,oEAAoE;AACpE,wBAAgB,YAAY,IAAI,UAAU,CAQzC;AAID;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAY5D"}

package/lib/typescript/commonjs/testing/clock.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A clock the test drives (ADS-11).
+ *
+ * Every bounded wait in this package — retry backoff, the request throttle, a
+ * consent form that never answers — is measured against a clock. Injecting this
+ * one is what lets a suite assert the behaviour at the boundary instead of
+ * sleeping and hoping.
+ */
+import type { Scheduler } from '../core/timers';
+/**
+ * A clock a test can move by hand.
+ *
+ * Retry backoff, app-open expiry, the undecided-state warning, and the
+ * ad-originated-return windows are all time-dependent, and all four must be
+ * assertable exactly rather than approximately. Advancing a clock makes "two
+ * retries, 2s then 4s" a precise assertion; sleeping would make it a flaky one.
+ *
+ * Callbacks fire in due order, and a callback scheduled *during* an advance is
+ * honored within the same advance if its deadline has also passed — matching how
+ * real timers behave when work chains.
+ */
+export interface TestClock {
+    now(): number;
+    advance(ms: number): void;
+    readonly scheduler: Scheduler;
+    pending(): number;
+}
+export declare function createTestClock(startMs?: number): TestClock;
+//# sourceMappingURL=clock.d.ts.map

package/lib/typescript/commonjs/testing/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../../../src/testing/clock.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS;IACzB,GAAG,IAAI,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,OAAO,IAAI,MAAM,CAAC;CAClB;AAED,wBAAgB,eAAe,CAAC,OAAO,SAAY,GAAG,SAAS,CA6C9D"}

package/lib/typescript/commonjs/testing/conformance.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What any `AdsEngine` must do (IOS-12, ADS-13).
+ *
+ * The same checks run against the fake engine and against the AdMob adapter over
+ * the provider mock (or the real provider, from a demo screen on a device), so a
+ * test that drives the fake proves something about the device path. The subject
+ * says how the provider delivers its callbacks; the checks only use the port.
+ */
+import { type Check, type ConformanceReport } from '@chipmobilesdk/rn-core/testing';
+import type { Reward } from '../config/types';
+import type { AdsEngine, EngineAdHandle } from '../engine/port';
+export interface AdsEngineSubject {
+    readonly engine: AdsEngine;
+    /** The provider finishes loading the ad behind `handle`. */
+    deliverLoad(handle: EngineAdHandle): void;
+    /** The provider grants a reward for the ad behind `handle`. */
+    deliverReward(handle: EngineAdHandle, reward: Reward): void;
+    /** The user closes the ad behind `handle`. */
+    deliverDismiss(handle: EngineAdHandle): void;
+}
+export interface AdsEngineHarness {
+    create(): AdsEngineSubject;
+}
+export declare const adsEngineChecks: readonly Check<AdsEngineHarness>[];
+export declare function runAdsEngineConformance(harness: AdsEngineHarness): Promise<ConformanceReport>;
+//# sourceMappingURL=conformance.d.ts.map

package/lib/typescript/commonjs/testing/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../../../../src/testing/conformance.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAGN,KAAK,KAAK,EACV,KAAK,iBAAiB,EACtB,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAiB,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE/E,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,4DAA4D;IAC5D,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAC1C,+DAA+D;IAC/D,aAAa,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5D,8CAA8C;IAC9C,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;CAC7C;AAED,MAAM,WAAW,gBAAgB;IAChC,MAAM,IAAI,gBAAgB,CAAC;CAC3B;AASD,eAAO,MAAM,eAAe,EAAE,SAAS,KAAK,CAAC,gBAAgB,CAAC,EAoE7D,CAAC;AAEF,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAE7F"}

package/lib/typescript/commonjs/testing/index.d.ts

@@ -0,0 +1,133 @@
+/**
+ * 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 type { AdFormat, FullScreenFormat, Reward } from '../config/types';
+export { createTestClock, type TestClock } from './clock';
+import { type TestClock } from './clock';
+import type { AdsEngine, EngineAdEvent, EngineConsentInfo, EngineConsentOptions, EnginePrivacy, EngineRequestOptions } from '../engine/port';
+export type FakeConsentCall = {
+    readonly kind: 'requestInfoUpdate';
+    readonly options: EngineConsentOptions;
+} | {
+    readonly kind: 'showFormIfRequired';
+} | {
+    readonly kind: 'showPrivacyOptionsForm';
+} | {
+    readonly kind: 'getInfo';
+} | {
+    readonly kind: 'reset';
+};
+/**
+ * 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.
+ */
+export interface HeldPrivacyOptionsForm {
+    /**
+     * The user closes the form. `info` is what the provider reports afterwards,
+     * merged over the current information; omit it for a user who changed nothing.
+     */
+    close(info?: Partial<EngineConsentInfo>): void;
+    /** The form fails while open. */
+    fail(cause?: unknown): void;
+}
+export type FakeEngineCall = {
+    readonly kind: 'initialize';
+    readonly privacy: EnginePrivacy;
+} | {
+    readonly kind: 'createFullScreen';
+    readonly format: FullScreenFormat;
+    readonly adUnitId: string;
+    readonly handleId: string;
+    /** Per-request privacy as the package sent it (FR-017's personalization half). */
+    readonly request?: EngineRequestOptions;
+} | {
+    readonly kind: 'show';
+    readonly handleId: string;
+} | {
+    readonly kind: 'dispose';
+    readonly handleId: string;
+};
+export interface FakeEngineOptions {
+    /** Simulates an unsupported platform or a missing bridge (FR-025). */
+    readonly available?: boolean;
+    /** Rejects `initialize`, for the failed-initialization path (FR-024). */
+    readonly failInitialize?: unknown;
+    /**
+     * Withholds the `loaded` callback so a load runs to its timeout. This is how
+     * FR-032's timeout behavior is tested without waiting on a real network.
+     */
+    readonly neverCallBack?: boolean;
+    /** Rejects `show`, for the display-failure path (FR-044). */
+    readonly failShow?: unknown;
+    /** Initial consent information. Defaults to the not-required, allowed case. */
+    readonly consentInfo?: Partial<EngineConsentInfo>;
+    /** Drives time for retry, expiry, and the undecided warning. */
+    readonly clock?: TestClock;
+}
+export interface FakeAdsEngine extends AdsEngine {
+    /** Every call the package made, in order. */
+    readonly calls: readonly FakeEngineCall[];
+    /** Ad unit ids passed to `createFullScreen`, in order — the SC-002 assertion. */
+    adUnitIds(): readonly string[];
+    /** Handle ids currently alive; non-empty after dispose means a leak. */
+    liveHandles(): readonly string[];
+    /** Emits a provider callback for one handle. The caller controls ordering. */
+    emit(handleId: string, event: EngineAdEvent): void;
+    /** Convenience for the common `loaded` case. */
+    completeLoad(handleId: string): void;
+    /** Emits a reward with a normalized payload. */
+    emitReward(handleId: string, reward?: Reward): void;
+    /** How many listeners are attached; must reach zero after cleanup (SC-008). */
+    listenerCount(): number;
+    /** Drops every recorded call, for tests that assert on a later window only. */
+    reset(): void;
+    /** The clock driving this engine's timers. Wire it into `createAds`. */
+    readonly clock: TestClock;
+    /** Moves the clock and fires anything due. */
+    advance(ms: number): void;
+    /** Every consent call the package made, in order (FR-113's assertion surface). */
+    readonly consentCalls: readonly FakeConsentCall[];
+    /** Sets what the consent platform will report from now on. */
+    setConsentInfo(info: Partial<EngineConsentInfo>): void;
+    /** Makes `requestInfoUpdate` reject — the flow must yield `error`, never granted. */
+    failConsentRequest(cause?: unknown): void;
+    /** Makes `showFormIfRequired` reject — dismissal is not consent (FR-106). */
+    failConsentForm(cause?: unknown): void;
+    /**
+     * What the privacy options form reports when the user closes it, merged over
+     * the current information. Unset, the form closes with nothing changed — the
+     * same as a user who opens it and backs out.
+     */
+    setPrivacyOptionsFormResult(info: Partial<EngineConsentInfo>): void;
+    /** Makes `showPrivacyOptionsForm` reject — a failure is never consent (FR-106). */
+    failPrivacyOptionsForm(cause?: unknown): void;
+    /** Holds the next privacy options form open until the test settles it. */
+    holdPrivacyOptionsForm(): HeldPrivacyOptionsForm;
+    /** Makes `getInfo` reject, for the case where even the re-read after a failed form fails. */
+    failConsentInfoRead(cause?: unknown): void;
+}
+/** The testID the fake banner renders under, for a test to find it by. */
+export declare const FAKE_BANNER_TEST_ID = "ads-fake-banner";
+export declare function createFakeAdsEngine(options?: FakeEngineOptions): FakeAdsEngine;
+export { adsEngineChecks, runAdsEngineConformance } from './conformance';
+export type { AdsEngineHarness, AdsEngineSubject } from './conformance';
+/** Google's official test ad unit for each format, as the package substitutes them (FR-011). */
+export declare function allTestAdUnits(): Readonly<Record<AdFormat, string>>;
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/commonjs/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/testing/index.ts"],"names":[],"mappings":"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"}

package/lib/typescript/module/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.js';
+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/module/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,YAAS,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"}