@chipmobilesdk/rn-ads 0.5.0 → 0.5.1

package/src/config/types.ts

@@ -1,321 +1,318 @@
-import type { AdsError } from '../diagnostics/errors';
-
-/**
- * Public configuration and state types (FR-001, FR-003, FR-004).
- *
- * Nothing here names a platform or an ad provider. That is the whole point:
- * adding an iOS adapter later contributes an optional `iosAdUnitId` and a second
- * engine implementation, and changes nothing a consumer already wrote (FR-006).
- *
- * The package persists none of this. Every value below lives for the lifetime of
- * one instance and is released by `dispose()`.
- */
-
-/**
- * Supported formats. Native and rewarded-interstitial remain deferred.
- *
- * `app_open` joined in 0.2.0. It is a member of this union rather than a
- * separate concept because FR-132 forbids a parallel vocabulary: app-open uses
- * the same placement states, events, and error codes as everything else. The
- * cost is that a consumer's exhaustive `switch` over this union stops compiling
- * — the one required migration step, documented in the 0.2.0 release notes.
- */
-export type AdFormat = 'banner' | 'interstitial' | 'rewarded' | 'app_open';
-
-/**
- * Formats that take over the screen, and so contend for the single-show lock.
- * App-open is included deliberately: two full-screen ads at once is a broken
- * app regardless of which formats produced them (FR-129).
- */
-export type FullScreenFormat = Extract<AdFormat, 'interstitial' | 'rewarded' | 'app_open'>;
-
-export function isFullScreenFormat(format: AdFormat): format is FullScreenFormat {
-	return format === 'interstitial' || format === 'rewarded' || format === 'app_open';
-}
-
-/**
- * Declared by the app, because the package cannot depend on any particular
- * configuration mechanism (FR-015). Cross-checked against the runtime dev flag
- * so a debug build claiming `production` is caught rather than trusted (FR-012).
- */
-export type Environment = 'development' | 'test' | 'production';
-
-/**
- * One logical ad slot. `key` is the app's own stable name — `home_footer`, not
- * an AdMob unit. Provider identifiers appear here in configuration and nowhere
- * else in consumer code (FR-003, FR-007).
- */
-export interface PlacementDefinition {
-	readonly key: string;
-	readonly format: AdFormat;
-	readonly androidAdUnitId: string;
-	/**
-	 * Additive placeholder for FR-006. Unused in v1 and never read by the Android
-	 * adapter — present so that adding iOS is a configuration change rather than a
-	 * type change for every existing consumer.
-	 */
-	readonly iosAdUnitId?: string;
-	/**
-	 * Per-placement retry, overriding `AdsConfig.retry` for this placement only.
-	 * Absent inherits; `false` turns retry off here while leaving it on elsewhere.
-	 *
-	 * An override *replaces* the instance-wide policy rather than merging into
-	 * it, so the effective policy for a placement is readable from configuration
-	 * without simulating a merge. Both are held to the same bounds, so an
-	 * override can narrow behavior but never exceed a ceiling (FR-136a).
-	 */
-	readonly retry?: RetryPolicy | false;
-	/**
-	 * Minimum milliseconds between two provider requests for this placement
-	 * (FR-140), added in 0.3.0.
-	 *
-	 * Absent takes the format-aware default: 60s for a banner, off for full-screen
-	 * formats. `0` turns it off here while leaving it on elsewhere.
-	 *
-	 * This is an **account-safety** floor, not a frequency cap: it limits how often
-	 * a placement may *ask* for an ad, never how often the app may *show* one. If
-	 * you are reaching for this to pace interstitials, that belongs in the app.
-	 */
-	readonly minRequestIntervalMs?: number;
-}
-
-/**
- * Bounded retry for failed loads. Off unless `AdsConfig.retry` is supplied —
- * upgrading from 0.1.0 without configuring this issues not one extra request
- * (FR-134).
- *
- * Only errors already flagged `retryable` are retried. Configuration errors,
- * consent errors, an unsupported platform, and a disabled or undecided instance
- * never are (FR-135).
- *
- * Backoff is exponential with a fixed x2 multiplier and no jitter. Jitter exists
- * to desynchronize a fleet hitting one server; a single device retrying its own
- * load has no herd to avoid, and omitting it keeps the attempt count an exact
- * assertion rather than a statistical one.
- */
-export interface RetryPolicy {
-	/** Attempts *after* the first. Default 2, bounds 1-5. */
-	readonly maxRetries?: number;
-	/** Delay before the first retry. Default 2000ms, bounds 500-30000. */
-	readonly initialDelayMs?: number;
-	/** Ceiling the doubling cannot pass. Default 30000ms, bounds 1000-60000. */
-	readonly maxDelayMs?: number;
-}
-
-/**
- * Whether the app wants ads, including the case where it does not know yet.
- *
- * The package never resolves `undecided` on the app's behalf and never learns
- * why the app chose what it chose — no entitlement, no receipt, no reason
- * (FR-119, FR-120).
- */
-export type Enablement = 'enabled' | 'disabled' | 'undecided';
-
-/**
- * Tools for exercising the consent flow from a device outside a
- * consent-required region.
- *
- * **Stripped entirely when `environment` is `production`.** That is enforced at
- * configuration validation rather than at each call site, so no path through the
- * consent module can forget it, and the fact that they were ignored is
- * observable through a `config_warning` event and `getIgnoredConsentTools()` —
- * not merely documented (FR-113).
- */
-export interface ConsentTestingOptions {
-	/** Makes the flow behave as though the device were in this region. */
-	readonly debugGeography?: 'disabled' | 'eea' | 'not_eea' | 'regulated_us_state' | 'other';
-	/** Clears any stored decision so the flow runs from the beginning. */
-	readonly resetOnStart?: boolean;
-}
-
-/**
- * Consent status, normalized. Carries no provider type and no payload (FR-104).
- *
- * Shaped so an iOS adapter can later express both a consent flow and the
- * platform's tracking-permission mechanism, plus the ordering between them,
- * without changing shape.
- */
-export type ConsentState =
-	/** Not yet asked. The initial value, and the value after a reset. */
-	| 'undetermined'
-	/** The provider reports this region does not require consent. */
-	| 'not_required'
-	/** Required and not yet obtained. */
-	| 'required'
-	/** Obtained. */
-	| 'obtained'
-	/**
-	 * The flow failed — a provider error, a network failure, a cancellation, or
-	 * a form dismissed without an answer. Never, under any circumstance, read as
-	 * consent granted (FR-106).
-	 */
-	| 'error';
-
-/**
- * Whether the user must be offered a way to change their consent choice
- * (FR-150), added in 0.4.0.
- *
- * The provider's verdict, forwarded — never the package's judgement about a
- * region, exactly as `not_required` in `ConsentState` is not. `required` is the
- * app's cue to show its own "Privacy options" entry; where that entry lives and
- * what it says stay the app's.
- *
- * `unknown` before the first successful `requestInfoUpdate()`, after `reset()`,
- * after a failed update, and on a platform with no adapter. It is not `not_required`:
- * an app that hides the entry on `unknown` is right to, but it must not conclude
- * the user has no right to one.
- */
-export type PrivacyOptionsRequirement = 'required' | 'not_required' | 'unknown';
-
-export interface ConsentSnapshot {
-	readonly state: ConsentState;
-	/** Always false when `state` is `error`. */
-	readonly canRequestAds: boolean;
-	readonly isFormAvailable: boolean;
-	/** Whether to offer a "change my choice" entry (FR-150). Added in 0.4.0. */
-	readonly privacyOptionsRequirement: PrivacyOptionsRequirement;
-	readonly error: AdsError | null;
-}
-
-/** Bounds exist because an unbounded timeout is the same defect as no timeout. */
-export interface TimeoutConfig {
-	readonly load?: number;
-	readonly show?: number;
-}
-
-export interface AdsConfig {
-	/**
-	 * FR-009. When `false`, every operation is a safe no-op reporting `disabled`.
-	 *
-	 * `'undecided'` was added in 0.2.0 for an app that cannot answer this at
-	 * construction time — one selling an ad-removal tier has to ask a store
-	 * first. Both boolean spellings keep their exact 0.1.0 meaning; widening an
-	 * *input* union cannot break a consumer, because consumers write this value
-	 * rather than switching on it (FR-114, BC-003).
-	 */
-	readonly enabled: boolean | 'undecided';
-	readonly environment: Environment;
-	readonly placements: readonly PlacementDefinition[];
-	readonly timeouts?: TimeoutConfig;
-	/** How long a loaded full-screen ad stays presentable (FR-034). */
-	readonly adValidityMs?: number;
-	/** Ignored entirely in `production` (FR-014). */
-	readonly testDeviceIds?: readonly string[];
-	/**
-	 * How long a loaded app-open ad stays presentable. Separate from
-	 * `adValidityMs`, which continues to govern interstitial and rewarded.
-	 *
-	 * Default 30 minutes, half the other formats' window. Note this is *our*
-	 * constraint, not the provider's — Google expires app-open ads after four
-	 * hours, which is longer than this package's general full-screen window. The
-	 * shorter window trades some fill for a fresher creative at the most
-	 * prominent moment in the app (FR-130).
-	 */
-	readonly appOpenValidityMs?: number;
-	/**
-	 * How long `enabled: 'undecided'` may go unresolved before the package emits
-	 * one diagnostic warning. Default 10 seconds.
-	 *
-	 * It warns and does nothing else. Resolving on the app's behalf would mean
-	 * guessing at exactly the business decision FR-120 forbids the package from
-	 * knowing.
-	 */
-	readonly undecidedWarningMs?: number;
-	/** Instance-wide retry. Absent means retry is entirely off (FR-134). */
-	readonly retry?: RetryPolicy;
-	/** Consent testing tools. Stripped in `production` (FR-113). */
-	readonly consentTesting?: ConsentTestingOptions;
-}
-
-/** Content ratings, normalized. Maps onto the provider's own rating scale. */
-export type AdContentRating = 'G' | 'PG' | 'T' | 'MA';
-
-/**
- * Supplied before initialization (FR-016). Never logged, never persisted
- * (FR-021). Everything except `canRequestAds` must reach the provider before it
- * initializes, which is why changing one afterwards reports
- * `requires_reinitialization` rather than pretending it applied (FR-020).
- */
-export interface PrivacyOptions {
-	/** The gate itself. False means no request may be made, for any reason. */
-	readonly canRequestAds: boolean;
-	/** Distinguishes "the user said no" from "we have not asked yet" (FR-018). */
-	readonly consentUndetermined?: boolean;
-	readonly childDirected?: boolean;
-	readonly underAgeOfConsent?: boolean;
-	readonly maxAdContentRating?: AdContentRating;
-	/** When false, the package requests non-personalized ads. */
-	readonly personalizedAds?: boolean;
-}
-
-/**
- * Why the consent gate is closed.
- *
- * The two original members keep their exact v1 meaning — the app's own gate —
- * so no existing consumer's interpretation changes. The two added in 0.2.0 name
- * the package's consent flow instead. The split exists because the gate has two
- * independent inputs that combine as most-restrictive-wins, and a refusal has to
- * say *which* of them is blocking or the app cannot act on it (FR-105a).
- */
-export type PrivacyBlockReason =
-	| 'consent_required'
-	| 'consent_undetermined'
-	| 'consent_flow_required'
-	| 'consent_flow_error';
-
-export type UnavailableReason = 'unsupported_platform' | 'provider_missing';
-
-/** FR-023. One per instance, observable without holding a provider object. */
-export type InitStatus =
-	| 'not_started'
-	| 'blocked'
-	| 'initializing'
-	| 'ready'
-	| 'disabled'
-	/**
-	 * The app has not decided whether ads are on yet — it is still waiting on
-	 * whatever answers that question, typically a store entitlement sync.
-	 *
-	 * Behaves exactly like `disabled` for requests (zero reach the provider) but
-	 * is deliberately a separate value. That distinction is the entire point:
-	 * `disabled` means a settled no, and a banner host can reclaim its space;
-	 * `undecided` means not yet, and the app may want to hold the space so a
-	 * paying user never sees an ad flash in and out (FR-116).
-	 */
-	| 'undecided'
-	| 'unavailable'
-	| 'failed';
-
-/**
- * FR-026. One per placement. Banners never reach `consumed` — they are
- * continuous, not single-use.
- */
-export type PlacementState =
-	| 'idle'
-	| 'loading'
-	| 'ready'
-	| 'showing'
-	| 'consumed'
-	| 'failed'
-	/** Mirrors `InitStatus.undecided` so the banner host can report it directly. */
-	| 'undecided'
-	/**
-	 * Refused by the per-placement request throttle (FR-140), added in 0.3.0.
-	 *
-	 * Deliberately distinct from `failed` and from a no-fill: nothing is wrong,
-	 * nothing was requested, and the same placement will work again shortly. An
-	 * app that collapses its ad slot on `failed` will usually want to collapse on
-	 * this too, but it must be able to tell the two apart when diagnosing why a
-	 * banner is absent.
-	 */
-	| 'throttled'
-	| 'unavailable';
-
-/** FR-047. The provider's reward descriptor, normalized. */
-export interface Reward {
-	readonly type: string;
-	readonly amount: number;
-}
-
-/** FR-005. Returned by every subscription; safe to call more than once. */
-export type Unsubscribe = () => void;
+import type { AdsError } from '../diagnostics/errors';
+
+/**
+ * Public configuration and state types (FR-001, FR-003, FR-004).
+ *
+ * Nothing here names a platform or an ad provider. That is the whole point:
+ * adding an iOS adapter later contributes an optional `iosAdUnitId` and a second
+ * engine implementation, and changes nothing a consumer already wrote (FR-006).
+ *
+ * The package persists none of this. Every value below lives for the lifetime of
+ * one instance and is released by `dispose()`.
+ */
+
+/**
+ * Supported formats. Native and rewarded-interstitial remain deferred.
+ *
+ * `app_open` joined in 0.2.0. It is a member of this union rather than a
+ * separate concept because FR-132 forbids a parallel vocabulary: app-open uses
+ * the same placement states, events, and error codes as everything else. The
+ * cost is that a consumer's exhaustive `switch` over this union stops compiling
+ * — the one required migration step, documented in the 0.2.0 release notes.
+ */
+export type AdFormat = 'banner' | 'interstitial' | 'rewarded' | 'app_open';
+
+/**
+ * Formats that take over the screen, and so contend for the single-show lock.
+ * App-open is included deliberately: two full-screen ads at once is a broken
+ * app regardless of which formats produced them (FR-129).
+ */
+export type FullScreenFormat = Extract<AdFormat, 'interstitial' | 'rewarded' | 'app_open'>;
+
+export function isFullScreenFormat(format: AdFormat): format is FullScreenFormat {
+	return format === 'interstitial' || format === 'rewarded' || format === 'app_open';
+}
+
+/**
+ * Declared by the app, because the package cannot depend on any particular
+ * configuration mechanism (FR-015). Cross-checked against the runtime dev flag
+ * so a debug build claiming `production` is caught rather than trusted (FR-012).
+ */
+export type Environment = 'development' | 'test' | 'production';
+
+/**
+ * One logical ad slot. `key` is the app's own stable name — `home_footer`, not
+ * an AdMob unit. Provider identifiers appear here in configuration and nowhere
+ * else in consumer code (FR-003, FR-007).
+ */
+export interface PlacementDefinition {
+	readonly key: string;
+	readonly format: AdFormat;
+	readonly androidAdUnitId: string;
+	/**
+	 * Additive placeholder for FR-006. Unused in v1 and never read by the Android
+	 * adapter — present so that adding iOS is a configuration change rather than a
+	 * type change for every existing consumer.
+	 */
+	readonly iosAdUnitId?: string;
+	/**
+	 * Per-placement retry, overriding `AdsConfig.retry` for this placement only.
+	 * Absent inherits; `false` turns retry off here while leaving it on elsewhere.
+	 *
+	 * An override *replaces* the instance-wide policy rather than merging into
+	 * it, so the effective policy for a placement is readable from configuration
+	 * without simulating a merge. Both are held to the same bounds, so an
+	 * override can narrow behavior but never exceed a ceiling (FR-136a).
+	 */
+	readonly retry?: RetryPolicy | false;
+	/**
+	 * Minimum milliseconds between two provider requests for this placement
+	 * (FR-140), added in 0.3.0.
+	 *
+	 * Absent takes the format-aware default: 60s for a banner, off for full-screen
+	 * formats. `0` turns it off here while leaving it on elsewhere.
+	 *
+	 * This is an **account-safety** floor, not a frequency cap: it limits how often
+	 * a placement may *ask* for an ad, never how often the app may *show* one. If
+	 * you are reaching for this to pace interstitials, that belongs in the app.
+	 */
+	readonly minRequestIntervalMs?: number;
+}
+
+/**
+ * Bounded retry for failed loads. Off unless `AdsConfig.retry` is supplied —
+ * upgrading from 0.1.0 without configuring this issues not one extra request
+ * (FR-134).
+ *
+ * Only errors already flagged `retryable` are retried. Configuration errors,
+ * consent errors, an unsupported platform, and a disabled or undecided instance
+ * never are (FR-135).
+ *
+ * Backoff is exponential with a fixed x2 multiplier and no jitter. Jitter exists
+ * to desynchronize a fleet hitting one server; a single device retrying its own
+ * load has no herd to avoid, and omitting it keeps the attempt count an exact
+ * assertion rather than a statistical one.
+ */
+export interface RetryPolicy {
+	/** Attempts *after* the first. Default 2, bounds 1-5. */
+	readonly maxRetries?: number;
+	/** Delay before the first retry. Default 2000ms, bounds 500-30000. */
+	readonly initialDelayMs?: number;
+	/** Ceiling the doubling cannot pass. Default 30000ms, bounds 1000-60000. */
+	readonly maxDelayMs?: number;
+}
+
+/**
+ * Whether the app wants ads, including the case where it does not know yet.
+ *
+ * The package never resolves `undecided` on the app's behalf and never learns
+ * why the app chose what it chose — no entitlement, no receipt, no reason
+ * (FR-119, FR-120).
+ */
+export type Enablement = 'enabled' | 'disabled' | 'undecided';
+
+/**
+ * Tools for exercising the consent flow from a device outside a
+ * consent-required region.
+ *
+ * **Stripped entirely when `environment` is `production`.** That is enforced at
+ * configuration validation rather than at each call site, so no path through the
+ * consent module can forget it, and the fact that they were ignored is
+ * observable through a `config_warning` event and `getIgnoredConsentTools()` —
+ * not merely documented (FR-113).
+ */
+export interface ConsentTestingOptions {
+	/** Makes the flow behave as though the device were in this region. */
+	readonly debugGeography?: 'disabled' | 'eea' | 'not_eea' | 'regulated_us_state' | 'other';
+	/** Clears any stored decision so the flow runs from the beginning. */
+	readonly resetOnStart?: boolean;
+}
+
+/**
+ * Consent status, normalized. Carries no provider type and no payload (FR-104).
+ *
+ * Shaped so an iOS adapter can later express both a consent flow and the
+ * platform's tracking-permission mechanism, plus the ordering between them,
+ * without changing shape.
+ */
+export type ConsentState =
+	/** Not yet asked. The initial value, and the value after a reset. */
+	| 'undetermined'
+	/** The provider reports this region does not require consent. */
+	| 'not_required'
+	/** Required and not yet obtained. */
+	| 'required'
+	/** Obtained. */
+	| 'obtained'
+	/**
+	 * The flow failed — a provider error, a network failure, a cancellation, or
+	 * a form dismissed without an answer. Never, under any circumstance, read as
+	 * consent granted (FR-106).
+	 */
+	| 'error';
+
+/**
+ * Whether the user must be offered a way to change their consent choice
+ * (FR-150), added in 0.4.0.
+ *
+ * The provider's verdict, forwarded — never the package's judgement about a
+ * region, exactly as `not_required` in `ConsentState` is not. `required` is the
+ * app's cue to show its own "Privacy options" entry; where that entry lives and
+ * what it says stay the app's.
+ *
+ * `unknown` before the first successful `requestInfoUpdate()`, after `reset()`,
+ * after a failed update, and on a platform with no adapter. It is not `not_required`:
+ * an app that hides the entry on `unknown` is right to, but it must not conclude
+ * the user has no right to one.
+ */
+export type PrivacyOptionsRequirement = 'required' | 'not_required' | 'unknown';
+
+export interface ConsentSnapshot {
+	readonly state: ConsentState;
+	/** Always false when `state` is `error`. */
+	readonly canRequestAds: boolean;
+	readonly isFormAvailable: boolean;
+	/** Whether to offer a "change my choice" entry (FR-150). Added in 0.4.0. */
+	readonly privacyOptionsRequirement: PrivacyOptionsRequirement;
+	readonly error: AdsError | null;
+}
+
+/** Bounds exist because an unbounded timeout is the same defect as no timeout. */
+export interface TimeoutConfig {
+	readonly load?: number;
+	readonly show?: number;
+}
+
+export interface AdsConfig {
+	/**
+	 * FR-009. When `false`, every operation is a safe no-op reporting `disabled`.
+	 *
+	 * `'undecided'` was added in 0.2.0 for an app that cannot answer this at
+	 * construction time — one selling an ad-removal tier has to ask a store
+	 * first. Both boolean spellings keep their exact 0.1.0 meaning; widening an
+	 * *input* union cannot break a consumer, because consumers write this value
+	 * rather than switching on it (FR-114, BC-003).
+	 */
+	readonly enabled: boolean | 'undecided';
+	readonly environment: Environment;
+	readonly placements: readonly PlacementDefinition[];
+	readonly timeouts?: TimeoutConfig;
+	/** How long a loaded full-screen ad stays presentable (FR-034). */
+	readonly adValidityMs?: number;
+	/** Ignored entirely in `production` (FR-014). */
+	readonly testDeviceIds?: readonly string[];
+	/**
+	 * How long a loaded app-open ad stays presentable. Separate from
+	 * `adValidityMs`, which continues to govern interstitial and rewarded.
+	 *
+	 * Default 30 minutes, half the other formats' window. Note this is *our*
+	 * constraint, not the provider's — Google expires app-open ads after four
+	 * hours, which is longer than this package's general full-screen window. The
+	 * shorter window trades some fill for a fresher creative at the most
+	 * prominent moment in the app (FR-130).
+	 */
+	readonly appOpenValidityMs?: number;
+	/**
+	 * How long `enabled: 'undecided'` may go unresolved before the package emits
+	 * one diagnostic warning. Default 10 seconds.
+	 *
+	 * It warns and does nothing else. Resolving on the app's behalf would mean
+	 * guessing at exactly the business decision FR-120 forbids the package from
+	 * knowing.
+	 */
+	readonly undecidedWarningMs?: number;
+	/** Instance-wide retry. Absent means retry is entirely off (FR-134). */
+	readonly retry?: RetryPolicy;
+	/** Consent testing tools. Stripped in `production` (FR-113). */
+	readonly consentTesting?: ConsentTestingOptions;
+}
+
+/** Content ratings, normalized. Maps onto the provider's own rating scale. */
+export type AdContentRating = 'G' | 'PG' | 'T' | 'MA';
+
+/**
+ * Supplied before initialization (FR-016). Never logged, never persisted
+ * (FR-021). Everything except `canRequestAds` must reach the provider before it
+ * initializes, which is why changing one afterwards reports
+ * `requires_reinitialization` rather than pretending it applied (FR-020).
+ */
+export interface PrivacyOptions {
+	/** The gate itself. False means no request may be made, for any reason. */
+	readonly canRequestAds: boolean;
+	/** Distinguishes "the user said no" from "we have not asked yet" (FR-018). */
+	readonly consentUndetermined?: boolean;
+	readonly childDirected?: boolean;
+	readonly underAgeOfConsent?: boolean;
+	readonly maxAdContentRating?: AdContentRating;
+	/** When false, the package requests non-personalized ads. */
+	readonly personalizedAds?: boolean;
+}
+
+/**
+ * Why the consent gate is closed.
+ *
+ * The two original members keep their exact v1 meaning — the app's own gate —
+ * so no existing consumer's interpretation changes. The two added in 0.2.0 name
+ * the package's consent flow instead. The split exists because the gate has two
+ * independent inputs that combine as most-restrictive-wins, and a refusal has to
+ * say *which* of them is blocking or the app cannot act on it (FR-105a).
+ */
+export type PrivacyBlockReason =
+	'consent_required' | 'consent_undetermined' | 'consent_flow_required' | 'consent_flow_error';
+
+export type UnavailableReason = 'unsupported_platform' | 'provider_missing';
+
+/** FR-023. One per instance, observable without holding a provider object. */
+export type InitStatus =
+	| 'not_started'
+	| 'blocked'
+	| 'initializing'
+	| 'ready'
+	| 'disabled'
+	/**
+	 * The app has not decided whether ads are on yet — it is still waiting on
+	 * whatever answers that question, typically a store entitlement sync.
+	 *
+	 * Behaves exactly like `disabled` for requests (zero reach the provider) but
+	 * is deliberately a separate value. That distinction is the entire point:
+	 * `disabled` means a settled no, and a banner host can reclaim its space;
+	 * `undecided` means not yet, and the app may want to hold the space so a
+	 * paying user never sees an ad flash in and out (FR-116).
+	 */
+	| 'undecided'
+	| 'unavailable'
+	| 'failed';
+
+/**
+ * FR-026. One per placement. Banners never reach `consumed` — they are
+ * continuous, not single-use.
+ */
+export type PlacementState =
+	| 'idle'
+	| 'loading'
+	| 'ready'
+	| 'showing'
+	| 'consumed'
+	| 'failed'
+	/** Mirrors `InitStatus.undecided` so the banner host can report it directly. */
+	| 'undecided'
+	/**
+	 * Refused by the per-placement request throttle (FR-140), added in 0.3.0.
+	 *
+	 * Deliberately distinct from `failed` and from a no-fill: nothing is wrong,
+	 * nothing was requested, and the same placement will work again shortly. An
+	 * app that collapses its ad slot on `failed` will usually want to collapse on
+	 * this too, but it must be able to tell the two apart when diagnosing why a
+	 * banner is absent.
+	 */
+	| 'throttled'
+	| 'unavailable';
+
+/** FR-047. The provider's reward descriptor, normalized. */
+export interface Reward {
+	readonly type: string;
+	readonly amount: number;
+}
+
+/** FR-005. Returned by every subscription; safe to call more than once. */
+export type Unsubscribe = () => void;

package/src/config/validate.ts

@@ -13,10 +13,7 @@
 import { AdsConfigError } from '../diagnostics/errors';
 import { resolvePlacementAdUnits, type ResolvedCatalog } from './resolveAdUnit';
 import { checkBand, resolveTimeouts, type ResolvedTimeouts } from '../core/timers';
-import {
-	defaultMinRequestIntervalMs,
-	MIN_REQUEST_INTERVAL_BOUNDS,
-} from '../core/requestThrottle';
+import { defaultMinRequestIntervalMs, MIN_REQUEST_INTERVAL_BOUNDS } from '../core/requestThrottle';
 import { toEnablement } from '../core/enablement';
 import { resolveEffectiveRetry, type ResolvedRetryPolicy } from '../core/retryPolicy';
 import type {