@chipmobilesdk/rn-ads 0.5.0 → 0.5.1

package/src/engine/port.ts

@@ -1,144 +1,144 @@
-/**
- * The internal engine port (NFR-008, FR-006).
- *
- * This interface names no platform and no ad provider. That is what makes an
- * iOS adapter an additive change: it implements this, and nothing in the public
- * contract moves. `core/` talks only to this shape; the AdMob bridge exists
- * behind exactly one implementation of it, in `admobEngine.ts`.
- *
- * Banners are absent on purpose. The provider owns a banner's whole lifecycle
- * through a React component, so `react/AdsBanner` adapts those callbacks
- * directly rather than routing them through a handle model that would have to
- * pretend a banner is a load-then-show resource.
- */
-
-import type { AdContentRating, FullScreenFormat, Reward, Unsubscribe } from '../config/types';
-
-/** Privacy state as the engine needs it — no consumer-facing shape leaks in. */
-export interface EnginePrivacy {
-	readonly childDirected?: boolean;
-	readonly underAgeOfConsent?: boolean;
-	readonly maxAdContentRating?: AdContentRating;
-	readonly personalizedAds?: boolean;
-	readonly testDeviceIds?: readonly string[];
-}
-
-/**
- * Privacy that applies to each ad request rather than to initialization.
- *
- * `personalizedAds` is here, not only in `EnginePrivacy`, because the provider
- * reads it per request and `updatePrivacy` may change it without
- * reinitializing: a request must carry the value current at request time.
- */
-export interface EngineRequestOptions {
-	readonly personalizedAds: boolean;
-}
-
-/**
- * Provider callbacks, normalized to the vocabulary the core state machines use.
- * `rewarded` and `dismissed` are separate members because they are separate
- * facts that can arrive in either order (FR-049).
- */
-export type EngineAdEvent =
-	| { readonly type: 'loaded' }
-	| { readonly type: 'failed'; readonly cause: unknown }
-	| { readonly type: 'opened' }
-	| { readonly type: 'clicked' }
-	| { readonly type: 'dismissed' }
-	| { readonly type: 'rewarded'; readonly reward: Reward };
-
-/** An opaque reference to one loaded ad. Never exposed publicly. */
-export interface EngineAdHandle {
-	readonly id: string;
-}
-
-/**
- * Consent status as the engine reports it — the provider's own vocabulary,
- * lowercased, with nothing provider-shaped attached. `core/consentFlow.ts`
- * normalizes this into the public `ConsentState`; keeping the two separate is
- * what lets an iOS adapter map a different mechanism onto the same public shape
- * without either side changing.
- */
-export interface EngineConsentInfo {
-	readonly status: 'unknown' | 'required' | 'not_required' | 'obtained';
-	readonly canRequestAds: boolean;
-	readonly isFormAvailable: boolean;
-	/** Whether the provider requires a "change my choice" entry point (FR-150). */
-	readonly privacyOptions: 'unknown' | 'required' | 'not_required';
-}
-
-export interface EngineConsentOptions {
-	/** Already stripped by config validation when the environment is production. */
-	readonly debugGeography?: 'disabled' | 'eea' | 'not_eea' | 'regulated_us_state' | 'other';
-	readonly underAgeOfConsent?: boolean;
-	readonly testDeviceIds?: readonly string[];
-}
-
-/**
- * The provider's consent platform, behind the same boundary as everything else.
- *
- * It is a separate member of `AdsEngine` rather than more methods on it because
- * it is a genuinely separate native module - the ads SDK and the consent SDK
- * initialize independently and neither requires the other.
- *
- * The package orchestrates; it never renders. `showFormIfRequired` asks the
- * provider to present its own form and reports what came back (FR-103).
- */
-export interface ConsentPort {
-	/** Refreshes consent information, applying any testing options. */
-	requestInfoUpdate(options: EngineConsentOptions): Promise<EngineConsentInfo>;
-	/** Presents the provider's form if one is required; a no-op otherwise. */
-	showFormIfRequired(): Promise<EngineConsentInfo>;
-	/**
-	 * Presents the provider's privacy options form, through which a user changes
-	 * an answer already given (FR-151). Resolves when the form closes, whether or
-	 * not anything changed; rejects if it could not be presented. The caller has
-	 * already checked the requirement, so the adapter does not re-check.
-	 */
-	showPrivacyOptionsForm(): Promise<EngineConsentInfo>;
-	/** Last known information without contacting the network. */
-	getInfo(): Promise<EngineConsentInfo>;
-	/** Clears the stored decision. Inert in production by configuration. */
-	reset(): void;
-}
-
-export interface AdsEngine {
-	/**
-	 * True when this platform has a working adapter. Checked before anything
-	 * else so an unsupported platform never loads the provider at all (FR-025).
-	 */
-	isAvailable(): boolean;
-
-	/**
-	 * Applies privacy configuration and then initializes the provider. The order
-	 * matters: child-directed and under-age flags only take effect if they reach
-	 * the provider before it initializes (FR-017, R9).
-	 *
-	 * The caller guarantees this is invoked at most once per instance; the
-	 * engine does not have to be idempotent itself.
-	 */
-	initialize(privacy: EnginePrivacy): Promise<void>;
-
-	/**
-	 * Creates and begins loading one full-screen ad. Resolves on request, not on
-	 * load. `request` is optional so engines written against 0.4.0 still satisfy
-	 * the port; an engine that ignores it requests personalized ads.
-	 */
-	createFullScreen(
-		format: FullScreenFormat,
-		adUnitId: string,
-		request?: EngineRequestOptions,
-	): Promise<EngineAdHandle>;
-
-	/** Presents a loaded ad. Rejects if the provider refuses to present. */
-	show(handle: EngineAdHandle): Promise<void>;
-
-	/** Provider callbacks for one handle. Returns an unsubscribe (FR-005). */
-	subscribe(handle: EngineAdHandle, listener: (event: EngineAdEvent) => void): Unsubscribe;
-
-	/** Releases the handle's provider resources. Safe to call more than once. */
-	dispose(handle: EngineAdHandle): void;
-
-	/** The provider's consent platform. Only touched if the app opts in (FR-102). */
-	readonly consent: ConsentPort;
-}
+/**
+ * The internal engine port (NFR-008, FR-006).
+ *
+ * This interface names no platform and no ad provider. That is what makes an
+ * iOS adapter an additive change: it implements this, and nothing in the public
+ * contract moves. `core/` talks only to this shape; the AdMob bridge exists
+ * behind exactly one implementation of it, in `admobEngine.ts`.
+ *
+ * Banners are absent on purpose. The provider owns a banner's whole lifecycle
+ * through a React component, so `react/AdsBanner` adapts those callbacks
+ * directly rather than routing them through a handle model that would have to
+ * pretend a banner is a load-then-show resource.
+ */
+
+import type { AdContentRating, FullScreenFormat, Reward, Unsubscribe } from '../config/types';
+
+/** Privacy state as the engine needs it — no consumer-facing shape leaks in. */
+export interface EnginePrivacy {
+	readonly childDirected?: boolean;
+	readonly underAgeOfConsent?: boolean;
+	readonly maxAdContentRating?: AdContentRating;
+	readonly personalizedAds?: boolean;
+	readonly testDeviceIds?: readonly string[];
+}
+
+/**
+ * Privacy that applies to each ad request rather than to initialization.
+ *
+ * `personalizedAds` is here, not only in `EnginePrivacy`, because the provider
+ * reads it per request and `updatePrivacy` may change it without
+ * reinitializing: a request must carry the value current at request time.
+ */
+export interface EngineRequestOptions {
+	readonly personalizedAds: boolean;
+}
+
+/**
+ * Provider callbacks, normalized to the vocabulary the core state machines use.
+ * `rewarded` and `dismissed` are separate members because they are separate
+ * facts that can arrive in either order (FR-049).
+ */
+export type EngineAdEvent =
+	| { readonly type: 'loaded' }
+	| { readonly type: 'failed'; readonly cause: unknown }
+	| { readonly type: 'opened' }
+	| { readonly type: 'clicked' }
+	| { readonly type: 'dismissed' }
+	| { readonly type: 'rewarded'; readonly reward: Reward };
+
+/** An opaque reference to one loaded ad. Never exposed publicly. */
+export interface EngineAdHandle {
+	readonly id: string;
+}
+
+/**
+ * Consent status as the engine reports it — the provider's own vocabulary,
+ * lowercased, with nothing provider-shaped attached. `core/consentFlow.ts`
+ * normalizes this into the public `ConsentState`; keeping the two separate is
+ * what lets an iOS adapter map a different mechanism onto the same public shape
+ * without either side changing.
+ */
+export interface EngineConsentInfo {
+	readonly status: 'unknown' | 'required' | 'not_required' | 'obtained';
+	readonly canRequestAds: boolean;
+	readonly isFormAvailable: boolean;
+	/** Whether the provider requires a "change my choice" entry point (FR-150). */
+	readonly privacyOptions: 'unknown' | 'required' | 'not_required';
+}
+
+export interface EngineConsentOptions {
+	/** Already stripped by config validation when the environment is production. */
+	readonly debugGeography?: 'disabled' | 'eea' | 'not_eea' | 'regulated_us_state' | 'other';
+	readonly underAgeOfConsent?: boolean;
+	readonly testDeviceIds?: readonly string[];
+}
+
+/**
+ * The provider's consent platform, behind the same boundary as everything else.
+ *
+ * It is a separate member of `AdsEngine` rather than more methods on it because
+ * it is a genuinely separate native module - the ads SDK and the consent SDK
+ * initialize independently and neither requires the other.
+ *
+ * The package orchestrates; it never renders. `showFormIfRequired` asks the
+ * provider to present its own form and reports what came back (FR-103).
+ */
+export interface ConsentPort {
+	/** Refreshes consent information, applying any testing options. */
+	requestInfoUpdate(options: EngineConsentOptions): Promise<EngineConsentInfo>;
+	/** Presents the provider's form if one is required; a no-op otherwise. */
+	showFormIfRequired(): Promise<EngineConsentInfo>;
+	/**
+	 * Presents the provider's privacy options form, through which a user changes
+	 * an answer already given (FR-151). Resolves when the form closes, whether or
+	 * not anything changed; rejects if it could not be presented. The caller has
+	 * already checked the requirement, so the adapter does not re-check.
+	 */
+	showPrivacyOptionsForm(): Promise<EngineConsentInfo>;
+	/** Last known information without contacting the network. */
+	getInfo(): Promise<EngineConsentInfo>;
+	/** Clears the stored decision. Inert in production by configuration. */
+	reset(): void;
+}
+
+export interface AdsEngine {
+	/**
+	 * True when this platform has a working adapter. Checked before anything
+	 * else so an unsupported platform never loads the provider at all (FR-025).
+	 */
+	isAvailable(): boolean;
+
+	/**
+	 * Applies privacy configuration and then initializes the provider. The order
+	 * matters: child-directed and under-age flags only take effect if they reach
+	 * the provider before it initializes (FR-017, R9).
+	 *
+	 * The caller guarantees this is invoked at most once per instance; the
+	 * engine does not have to be idempotent itself.
+	 */
+	initialize(privacy: EnginePrivacy): Promise<void>;
+
+	/**
+	 * Creates and begins loading one full-screen ad. Resolves on request, not on
+	 * load. `request` is optional so engines written against 0.4.0 still satisfy
+	 * the port; an engine that ignores it requests personalized ads.
+	 */
+	createFullScreen(
+		format: FullScreenFormat,
+		adUnitId: string,
+		request?: EngineRequestOptions,
+	): Promise<EngineAdHandle>;
+
+	/** Presents a loaded ad. Rejects if the provider refuses to present. */
+	show(handle: EngineAdHandle): Promise<void>;
+
+	/** Provider callbacks for one handle. Returns an unsubscribe (FR-005). */
+	subscribe(handle: EngineAdHandle, listener: (event: EngineAdEvent) => void): Unsubscribe;
+
+	/** Releases the handle's provider resources. Safe to call more than once. */
+	dispose(handle: EngineAdHandle): void;
+
+	/** The provider's consent platform. Only touched if the app opts in (FR-102). */
+	readonly consent: ConsentPort;
+}

package/src/engine/testAdUnits.ts

@@ -1,61 +1,61 @@
-/**
- * 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';
-
-/** Android. iOS units are added alongside these when the iOS adapter lands (FR-006). */
-const ANDROID_TEST_AD_UNITS: Readonly<Record<AdFormat, string>> = {
-	// The adaptive-banner unit, not the fixed-size one, because adaptive is the
-	// format this package actually requests (FR-038).
-	banner: 'ca-app-pub-3940256099942544/9214589741',
-	interstitial: 'ca-app-pub-3940256099942544/1033173712',
-	rewarded: 'ca-app-pub-3940256099942544/5224354917',
-	// Added in 0.2.0 alongside the app-open format. Cross-checked against the
-	// bridge's own `TestIds.APP_OPEN` at 16.0.3.
-	app_open: 'ca-app-pub-3940256099942544/9257395921',
-};
-
-export function testAdUnitFor(format: AdFormat): string {
-	return ANDROID_TEST_AD_UNITS[format];
-}
-
-/**
- * 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 function isOfficialTestAdUnit(adUnitId: string): boolean {
-	for (const value of Object.values(ANDROID_TEST_AD_UNITS)) {
-		if (value === adUnitId) {
-			return true;
-		}
-	}
-	return false;
-}
-
-/** Exposed for the package's own tests and for documentation generation. */
-export function allTestAdUnits(): Readonly<Record<AdFormat, string>> {
-	return ANDROID_TEST_AD_UNITS;
-}
+/**
+ * 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';
+
+/** Android. iOS units are added alongside these when the iOS adapter lands (FR-006). */
+const ANDROID_TEST_AD_UNITS: Readonly<Record<AdFormat, string>> = {
+	// The adaptive-banner unit, not the fixed-size one, because adaptive is the
+	// format this package actually requests (FR-038).
+	banner: 'ca-app-pub-3940256099942544/9214589741',
+	interstitial: 'ca-app-pub-3940256099942544/1033173712',
+	rewarded: 'ca-app-pub-3940256099942544/5224354917',
+	// Added in 0.2.0 alongside the app-open format. Cross-checked against the
+	// bridge's own `TestIds.APP_OPEN` at 16.0.3.
+	app_open: 'ca-app-pub-3940256099942544/9257395921',
+};
+
+export function testAdUnitFor(format: AdFormat): string {
+	return ANDROID_TEST_AD_UNITS[format];
+}
+
+/**
+ * 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 function isOfficialTestAdUnit(adUnitId: string): boolean {
+	for (const value of Object.values(ANDROID_TEST_AD_UNITS)) {
+		if (value === adUnitId) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/** Exposed for the package's own tests and for documentation generation. */
+export function allTestAdUnits(): Readonly<Record<AdFormat, string>> {
+	return ANDROID_TEST_AD_UNITS;
+}