@chipmobilesdk/rn-ads 0.6.0 → 0.7.0

package/src/core/instance/load.ts

@@ -0,0 +1,426 @@
+/**
+ * Loading full-screen ads (FR-029, FR-134 – FR-140) and the provider callbacks
+ * that follow a load through its whole cycle.
+ */
+import {
+	isFullScreenFormat,
+	type AdFormat,
+	type FullScreenFormat,
+	type PlacementDefinition,
+} from '../../config/types';
+import { AdsError, normalizeProviderError } from '../../diagnostics/errors';
+import type { EngineAdEvent } from '../../engine/port';
+import { canRequest } from '../initMachine';
+import { canLoad } from '../placementMachine';
+import { toEngineRequest } from '../privacyGate';
+import { canRetry, delayForAttempt } from '../retryPolicy';
+import type { InstanceContext } from './context';
+import { currentGate, gateRefusal } from './gate';
+import type { LoadResult } from './types';
+
+export function unknownPlacement(
+	context: InstanceContext,
+	placementKey: string,
+	operation: 'load' | 'show',
+): LoadResult & { status: 'failed' } {
+	return {
+		status: 'failed',
+		error: new AdsError('placement_not_found', {
+			operation,
+			placementKey,
+			message: `unknown placement "${placementKey}"; configured keys are ${[...context.resolved.placements.keys()].join(', ')}`,
+		}),
+	};
+}
+
+export function createLoader(context: InstanceContext): {
+	load(placementKey: string): Promise<LoadResult>;
+} {
+	const { state, engine, events, timers, resolved, lock, adReturn, now } = context;
+
+	/**
+	 * Takes a throttle slot, or reports the refusal (FR-140). `null` means
+	 * proceed. A placement still holding a `ready` ad keeps that state: the
+	 * refusal is about asking again, and overwriting it would strand an ad that
+	 * was already paid for (ADS-01).
+	 */
+	function checkThrottle(key: string, format: AdFormat): LoadResult | null {
+		const minRequestIntervalMs = resolved.minRequestIntervalByKey.get(key) ?? 0;
+		const decision = context.requestThrottle.tryAcquire(key, minRequestIntervalMs);
+		if (decision.allowed) {
+			return null;
+		}
+		const runtime = context.placements.get(key);
+		if (runtime && runtime.snapshot.state !== 'ready') {
+			context.setPlacement(key, { ...runtime.snapshot, state: 'throttled' });
+		}
+		events.emit({
+			type: 'request_throttled',
+			timestamp: now(),
+			placementKey: key,
+			format,
+			retryAfterMs: decision.retryAfterMs,
+			minRequestIntervalMs,
+		});
+		return { status: 'throttled', retryAfterMs: decision.retryAfterMs };
+	}
+
+	function handleEngineEvent(
+		key: string,
+		definition: PlacementDefinition,
+		event: EngineAdEvent,
+	): void {
+		// After dispose nothing is honored (FR-035, SC-008).
+		const runtime = context.placements.get(key);
+		if (state.disposed || !runtime) {
+			return;
+		}
+		const base = {
+			timestamp: now(),
+			placementKey: key,
+			format: definition.format,
+			correlationId: runtime.correlationId ?? undefined,
+		};
+		switch (event.type) {
+			case 'opened':
+				// The provider confirming an ad is on screen arms ad-originated return
+				// detection (FR-128); the app's own background report arrives too late.
+				if (isFullScreenFormat(definition.format)) {
+					adReturn.noteFullScreenShown(now());
+				}
+				events.emit({ ...base, type: 'display_started' });
+				// R5: no impression callback for full-screen formats, so this one is
+				// derived from the ad opening, and labelled as such.
+				events.emit({ ...base, type: 'impression', source: 'derived' });
+				return;
+			case 'clicked':
+				// A background moments later is "the ad opened a browser" (FR-128).
+				adReturn.noteClick(now());
+				events.emit({ ...base, type: 'click' });
+				return;
+			case 'rewarded': {
+				const first = runtime.rewarded?.confirmReward(event.reward) ?? null;
+				if (first) {
+					events.emit({ ...base, type: 'reward_earned', reward: first });
+				}
+				return;
+			}
+			case 'dismissed': {
+				const rewardedFirst = runtime.rewarded ? runtime.rewarded.dismiss() : true;
+				if (runtime.dismissed || !rewardedFirst) {
+					return;
+				}
+				runtime.dismissed = true;
+				lock.release(key);
+				runtime.cancelShowTimer?.();
+				runtime.cancelShowTimer = null;
+				events.emit({
+					...base,
+					type: 'dismissed',
+					rewardEarned: runtime.rewarded ? runtime.rewarded.rewardEarned : undefined,
+				});
+				context.dispatchPlacement(key, { type: 'DISMISSED' });
+				// Deliberately NOT released: FR-049 handles the reward and the
+				// dismissal in either order, and a provider that confirms the reward
+				// after closing would otherwise reach a torn-down listener. At most one
+				// handle and one listener per placement, released by the next load or
+				// by dispose().
+				return;
+			}
+			case 'failed': {
+				const normalized = normalizeProviderError(
+					event.cause,
+					{
+						operation: 'show',
+						placementKey: key,
+						format: definition.format,
+					},
+					event.kind,
+				);
+				lock.release(key);
+				events.emit({ ...base, type: 'display_failed', error: normalized });
+				context.dispatchPlacement(key, { type: 'SHOW_FAILED', error: normalized });
+				context.releasePlacementResources(key);
+				return;
+			}
+			default:
+		}
+	}
+
+	function loadFailed(
+		key: string,
+		format: FullScreenFormat,
+		correlationId: string,
+		error: AdsError,
+	): LoadResult {
+		events.emit({
+			type: 'load_failed',
+			timestamp: now(),
+			placementKey: key,
+			format,
+			correlationId,
+			error,
+		});
+		context.dispatchPlacement(key, { type: 'LOAD_FAILED', error });
+		return error.code === 'no_fill' ? { status: 'no_fill' } : { status: 'failed', error };
+	}
+
+	function loadFullScreen(
+		key: string,
+		definition: PlacementDefinition & { format: FullScreenFormat },
+		adUnitId: string,
+		correlationId: string,
+	): Promise<LoadResult> {
+		const runtime = context.placements.get(key);
+		const { format } = definition;
+		const startedAt = now();
+		if (!runtime) {
+			return Promise.resolve({ status: 'unavailable', reason: 'provider_missing' });
+		}
+
+		return new Promise<LoadResult>(resolve => {
+			let settled = false;
+			const finish = (result: LoadResult) => {
+				if (settled) {
+					return;
+				}
+				settled = true;
+				runtime.cancelLoadTimer?.();
+				runtime.cancelLoadTimer = null;
+				runtime.inFlightLoad = null;
+				if (runtime.abortLoad === finish) {
+					runtime.abortLoad = null;
+				}
+				resolve(result);
+			};
+			// `settled` makes this safe: a handle the provider hands back after an
+			// abort is disposed by the `.then` below instead of adopted.
+			runtime.abortLoad = finish;
+
+			runtime.cancelLoadTimer = timers.after(resolved.timeouts.load, () => {
+				const error = new AdsError('load_timeout', {
+					operation: 'load',
+					placementKey: key,
+					format,
+					message: `load timed out after ${resolved.timeouts.load}ms`,
+				});
+				loadFailed(key, format, correlationId, error);
+				context.releasePlacementResources(key);
+				finish({ status: 'timeout' });
+			});
+
+			engine
+				.createFullScreen(format, adUnitId, toEngineRequest(state.currentPrivacy))
+				.then(handle => {
+					if (state.disposed || settled) {
+						engine.dispose(handle);
+						return;
+					}
+					runtime.handle = handle;
+					runtime.unsubscribeEngine = engine.subscribe(handle, event => {
+						if (event.type === 'loaded') {
+							context.dispatchPlacement(key, { type: 'LOADED', atMs: now() });
+							events.emit({
+								type: 'loaded',
+								timestamp: now(),
+								placementKey: key,
+								format,
+								correlationId,
+								durationMs: now() - startedAt,
+							});
+							finish({ status: 'loaded', correlationId });
+						} else if (event.type === 'failed') {
+							const error = normalizeProviderError(
+								event.cause,
+								{
+									operation: 'load',
+									placementKey: key,
+									format,
+								},
+								event.kind,
+							);
+							const result = loadFailed(key, format, correlationId, error);
+							context.releasePlacementResources(key);
+							finish(result);
+						} else {
+							handleEngineEvent(key, definition, event);
+						}
+					});
+				})
+				.catch(error => {
+					const normalized = normalizeProviderError(error, {
+						operation: 'load',
+						placementKey: key,
+						format,
+					});
+					finish(loadFailed(key, format, correlationId, normalized));
+				});
+		});
+	}
+
+	/**
+	 * One load, plus however many bounded retries the policy allows (FR-134).
+	 *
+	 * Off unless configured. When on, only errors flagged `retryable` are retried
+	 * — a configuration or consent failure is a state another attempt cannot
+	 * change, and retrying it would spend a billable request on a certainty
+	 * (FR-135). Every attempt is emitted before it is waited on, with the cycle's
+	 * correlation id, so the stream reconciles against a bill (FR-138).
+	 */
+	async function loadWithRetry(
+		key: string,
+		definition: PlacementDefinition & { format: FullScreenFormat },
+		adUnitId: string,
+		correlationId: string,
+	): Promise<LoadResult> {
+		const runtime = context.placements.get(key);
+		const policy = resolved.retryByKey.get(key) ?? null;
+		for (;;) {
+			const result = await loadFullScreen(key, definition, adUnitId, correlationId);
+			if (result.status === 'loaded' || state.disposed || !runtime) {
+				return result;
+			}
+			const error = retryableErrorOf(result, key);
+			// A refusal is not a failure to retry: nothing was requested. And a retry
+			// is a new provider request, so it needs the whole gate (FR-017).
+			if (
+				!error?.retryable ||
+				!policy ||
+				!canRetry(policy, runtime.retryAttempts) ||
+				!currentGate(context).allowed
+			) {
+				return result;
+			}
+			runtime.retryAttempts += 1;
+			// A retry is a provider request like any other, so it waits at least as
+			// long as the placement's floor requires (FR-140, ADS-07): a 2 s backoff
+			// on a placement with a 20 s floor waits 20 s.
+			const floor = resolved.minRequestIntervalByKey.get(key) ?? 0;
+			const delayMs = Math.max(
+				delayForAttempt(policy, runtime.retryAttempts),
+				context.requestThrottle.waitFor(key, floor),
+			);
+			events.emit({
+				type: 'retry_scheduled',
+				timestamp: now(),
+				placementKey: key,
+				format: definition.format,
+				correlationId,
+				attempt: runtime.retryAttempts,
+				delayMs,
+				error,
+			});
+			const waited = await new Promise<boolean>(resolve => {
+				const cancelTimer = timers.after(delayMs, () => {
+					runtime.cancelRetry = null;
+					resolve(true);
+				});
+				// A disable or dispose that cancels resolves this wait as "do not
+				// continue" rather than leaving a promise nobody will settle.
+				runtime.cancelRetry = () => {
+					cancelTimer();
+					runtime.cancelRetry = null;
+					resolve(false);
+				};
+			});
+			if (!waited || state.disposed || !currentGate(context).allowed) {
+				return result;
+			}
+			// Recorded, so the next load is measured from this request. Refused only
+			// if the clock jumped while waiting; then the retry is skipped, not sent.
+			if (!context.requestThrottle.tryAcquire(key, floor).allowed) {
+				return result;
+			}
+			context.dispatchPlacement(key, { type: 'LOAD' });
+		}
+	}
+
+	return {
+		async load(placementKey) {
+			if (state.disposed) {
+				return { status: 'unavailable', reason: 'provider_missing' };
+			}
+			const found = context.placement(placementKey);
+			if (!found) {
+				return unknownPlacement(context, placementKey, 'load');
+			}
+			const { runtime, definition } = found;
+			const refusal = gateRefusal(context);
+			if (refusal) {
+				context.emitRefusal('load', refusal, placementKey, definition.format);
+				return refusal;
+			}
+			const fail = (
+				code: 'not_ready' | 'busy' | 'format_mismatch',
+				detail: { format?: AdFormat; message?: string } = {},
+			): LoadResult => ({
+				status: 'failed',
+				error: new AdsError(code, { operation: 'load', placementKey, ...detail }),
+			});
+			if (!canRequest(state.init.status)) {
+				return fail('not_ready', {
+					format: definition.format,
+					message: 'initialize() must complete before loading',
+				});
+			}
+			if (!isFullScreenFormat(definition.format)) {
+				return fail('format_mismatch', {
+					format: definition.format,
+					message: `"${placementKey}" is a banner; banners render through <AdsBanner> rather than load()`,
+				});
+			}
+			// FR-029: a repeat load while one is in flight joins it.
+			if (runtime.inFlightLoad) {
+				return runtime.inFlightLoad;
+			}
+			if (runtime.snapshot.state === 'showing') {
+				return fail('busy');
+			}
+			if (!canLoad(runtime.snapshot.state)) {
+				return fail('not_ready');
+			}
+			// FR-140. After the in-flight join, so a caller that arrived twice is not
+			// charged; after the busy and not-ready guards, so a load that would not
+			// request anything spends no slot; and before the correlation id, because
+			// a refused request is not a cycle.
+			const throttled = checkThrottle(placementKey, definition.format);
+			if (throttled) {
+				return throttled;
+			}
+
+			context.releasePlacementResources(placementKey);
+			const correlationId = context.correlation.next();
+			runtime.correlationId = correlationId;
+			runtime.dismissed = false;
+			context.dispatchPlacement(placementKey, { type: 'LOAD' });
+			context.setPlacement(placementKey, { ...runtime.snapshot, correlationId });
+			events.emit({
+				type: 'load_started',
+				timestamp: now(),
+				placementKey,
+				format: definition.format,
+				correlationId,
+			});
+			const adUnitId = resolved.catalog.byKey.get(placementKey) ?? '';
+			runtime.retryAttempts = 0;
+			const fullScreen = { ...definition, format: definition.format };
+			const promise = loadWithRetry(placementKey, fullScreen, adUnitId, correlationId);
+			runtime.inFlightLoad = promise;
+			return promise;
+		},
+	};
+}
+
+/** The error a failed attempt carries, for the retry decision; null for a refusal. */
+function retryableErrorOf(result: LoadResult, key: string): AdsError | null {
+	switch (result.status) {
+		case 'failed':
+			return result.error;
+		case 'no_fill':
+			return new AdsError('no_fill', { operation: 'load', placementKey: key });
+		case 'timeout':
+			return new AdsError('load_timeout', { operation: 'load', placementKey: key });
+		default:
+			return null;
+	}
+}

package/src/core/instance/show.ts

@@ -0,0 +1,202 @@
+/**
+ * Showing full-screen ads (FR-028, FR-030, FR-034, FR-128) and the foreground
+ * re-evaluation of what was loaded.
+ */
+import { isFullScreenFormat } from '../../config/types';
+import { AdsError, normalizeProviderError } from '../../diagnostics/errors';
+import { canShow } from '../placementMachine';
+import { createRewardedSession } from '../rewardedSession';
+import { isStale } from '../timers';
+import { validityFor, type InstanceContext } from './context';
+import { gateRefusal } from './gate';
+import { unknownPlacement } from './load';
+import type { ShowResult } from './types';
+
+export function createShower(context: InstanceContext): {
+	show(placementKey: string): Promise<ShowResult>;
+	setAppActive(active: boolean): void;
+} {
+	const { state, engine, events, timers, resolved, lock, adReturn, now } = context;
+
+	/** Releases and expires a `ready` ad that outlived its validity (FR-034). */
+	function expireIfStale(key: string, at: number): boolean {
+		const found = context.placement(key);
+		if (!found) {
+			return false;
+		}
+		const { snapshot } = found.runtime;
+		if (
+			snapshot.state !== 'ready' ||
+			snapshot.loadedAtMs === null ||
+			!isStale(snapshot.loadedAtMs, at, validityFor(context, found.definition.format))
+		) {
+			return false;
+		}
+		context.releasePlacementResources(key);
+		context.dispatchPlacement(key, { type: 'EXPIRE' });
+		return true;
+	}
+
+	return {
+		async show(placementKey) {
+			if (state.disposed) {
+				return { status: 'unavailable', reason: 'provider_missing' };
+			}
+			const found = context.placement(placementKey);
+			if (!found) {
+				return unknownPlacement(context, placementKey, 'show');
+			}
+			const { runtime, definition } = found;
+			if (!isFullScreenFormat(definition.format)) {
+				return {
+					status: 'failed',
+					error: new AdsError('format_mismatch', {
+						operation: 'show',
+						placementKey,
+						format: definition.format,
+						message: `"${placementKey}" is a banner; banners are rendered, not shown`,
+					}),
+				};
+			}
+			const refusal = gateRefusal(context);
+			if (refusal) {
+				context.emitRefusal('show', refusal, placementKey, definition.format);
+				return refusal;
+			}
+			// FR-028: never open an ad while the app is not in front of the user.
+			if (!state.appActive) {
+				return { status: 'app_inactive' };
+			}
+			// FR-128. Only app-open is refused: it is the format that would fire on
+			// the return from an ad. An interstitial at the same moment is the app's
+			// own choice, and refusing it would be policy rather than capability.
+			if (definition.format === 'app_open' && adReturn.isRefusing(now())) {
+				return { status: 'ad_originated_return' };
+			}
+			if (runtime.snapshot.state === 'consumed') {
+				return { status: 'consumed' };
+			}
+			// FR-034: a stale ad is not shown and is not reported ready.
+			if (expireIfStale(placementKey, now())) {
+				return { status: 'not_ready' };
+			}
+			const handle = runtime.handle;
+			if (!canShow(runtime.snapshot.state) || !handle) {
+				return { status: 'not_ready' };
+			}
+			// FR-030. Never queued: a refused show is refused now, not deferred to a
+			// moment the app never chose.
+			if (!lock.acquire(placementKey)) {
+				return { status: 'busy' };
+			}
+
+			const correlationId = runtime.correlationId ?? context.correlation.next();
+			runtime.rewarded = definition.format === 'rewarded' ? createRewardedSession() : null;
+			context.dispatchPlacement(placementKey, { type: 'SHOW' });
+
+			const failShow = (error: AdsError): void => {
+				lock.release(placementKey);
+				events.emit({
+					type: 'display_failed',
+					timestamp: now(),
+					placementKey,
+					format: definition.format,
+					correlationId,
+					error,
+				});
+				context.dispatchPlacement(placementKey, { type: 'SHOW_FAILED', error });
+				context.releasePlacementResources(placementKey);
+			};
+
+			// ADS-09. Whichever of the provider's answer and the timeout comes first
+			// decides the result; the other must not act on it a second time.
+			let settled = false;
+			const showTimeout = new Promise<ShowResult>(resolve => {
+				runtime.cancelShowTimer = timers.after(resolved.timeouts.show, () => {
+					runtime.cancelShowTimer = null;
+					if (settled) {
+						return;
+					}
+					settled = true;
+					// The provider may still open the ad. Its handle and listener stay, so
+					// a late open, reward or dismissal is still heard and the reward is not
+					// lost (FR-049); they go with the next load or with dispose. The lock is
+					// released now and taken back if the ad does open.
+					lock.release(placementKey);
+					const error = new AdsError('show_timeout', {
+						operation: 'show',
+						placementKey,
+						format: definition.format,
+						message: `show timed out after ${resolved.timeouts.show}ms`,
+					});
+					events.emit({
+						type: 'display_failed',
+						timestamp: now(),
+						placementKey,
+						format: definition.format,
+						correlationId,
+						error,
+					});
+					context.dispatchPlacement(placementKey, { type: 'SHOW_FAILED', error });
+					resolve({ status: 'timeout' });
+				});
+			});
+
+			const attempt = engine
+				.show(handle)
+				.then<ShowResult>(() => {
+					if (settled) {
+						// Opened after the timeout was reported. It is on screen now, so it
+						// holds the one full-screen lock until it is dismissed (FR-030).
+						lock.acquire(placementKey);
+						return { status: 'timeout' };
+					}
+					settled = true;
+					runtime.cancelShowTimer?.();
+					runtime.cancelShowTimer = null;
+					return { status: 'shown', correlationId };
+				})
+				.catch<ShowResult>(error => {
+					if (settled) {
+						// Failed after the timeout already said so: nothing new to report,
+						// and nothing will show, so its resources can go.
+						context.releasePlacementResources(placementKey);
+						return { status: 'timeout' };
+					}
+					settled = true;
+					runtime.cancelShowTimer?.();
+					runtime.cancelShowTimer = null;
+					const normalized = normalizeProviderError(error, {
+						operation: 'show',
+						placementKey,
+						format: definition.format,
+					});
+					failShow(normalized);
+					return { status: 'failed', error: normalized };
+				});
+
+			return Promise.race([attempt, showTimeout]);
+		},
+
+		setAppActive(active) {
+			if (state.disposed) {
+				return;
+			}
+			state.appActive = active;
+			if (!active) {
+				// Arming happens when the provider reports an ad opened; this event can
+				// arrive after the ad is gone. All it adds is the browser case, a
+				// background closely following a click (FR-128).
+				adReturn.noteBackground(now());
+				return;
+			}
+			adReturn.noteForeground(now());
+			// FR-034: an ad that went stale while the app was away stops reporting
+			// `ready` before the app offers a button that would fail on tap.
+			const current = now();
+			for (const key of context.placements.keys()) {
+				expireIfStale(key, current);
+			}
+		},
+	};
+}