@chipmobilesdk/rn-ads 0.6.0 → 0.8.0

package/lib/typescript/module/config/types.d.ts

@@ -0,0 +1,280 @@
+import type { AdsError } from '../diagnostics/errors.js';
+/**
+ * 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 declare function isFullScreenFormat(format: AdFormat): format is FullScreenFormat;
+/**
+ * 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;
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/module/config/types.d.ts.map

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

package/lib/typescript/module/config/validate.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Catalog and configuration validation (FR-008), plus the fail-closed check
+ * that substitution cannot cover (FR-012).
+ *
+ * Configuration faults throw rather than returning a result. They mean the app
+ * is wired wrong, and no runtime status could describe a usable outcome — every
+ * other failure in this package is a typed result instead.
+ *
+ * Every message names the offending placement key. An error that says only
+ * "invalid configuration" makes the integrator hunt through a catalog by hand.
+ */
+import { type ResolvedCatalog } from './resolveAdUnit.js';
+import { type ResolvedTimeouts } from '../core/timers.js';
+import { type ResolvedRetryPolicy } from '../core/retryPolicy.js';
+import type { AdsConfig, ConsentTestingOptions, Enablement, Environment, PlacementDefinition } from './types.js';
+export interface ValidateOptions {
+    /**
+     * Whether this is a debug build. Injected rather than read from `__DEV__`
+     * directly so the fail-closed rule is testable without manipulating a global
+     * the test runner also depends on.
+     */
+    readonly isDevBuild: boolean;
+}
+export interface ResolvedConfig {
+    readonly enablement: Enablement;
+    readonly environment: Environment;
+    readonly placements: ReadonlyMap<string, PlacementDefinition>;
+    readonly catalog: ResolvedCatalog;
+    readonly timeouts: ResolvedTimeouts;
+    /** Empty in production regardless of what was configured (FR-014). */
+    readonly testDeviceIds: readonly string[];
+    /** Effective retry per placement. `null` means retry is off there (FR-134). */
+    readonly retryByKey: ReadonlyMap<string, ResolvedRetryPolicy | null>;
+    /**
+     * Effective minimum interval between provider requests, per placement
+     * (FR-140). Zero means the throttle is off for that placement.
+     */
+    readonly minRequestIntervalByKey: ReadonlyMap<string, number>;
+    /** Stripped entirely in production (FR-113). */
+    readonly consentTesting: ConsentTestingOptions | undefined;
+    /**
+     * Which consent tools were dropped because the environment is production.
+     * Surfaced so the inertness is observable rather than merely documented —
+     * the same treatment FR-011a gives substituted ad units.
+     */
+    readonly ignoredConsentTools: readonly string[];
+}
+export declare function validateConfig(config: AdsConfig, options: ValidateOptions): ResolvedConfig;
+//# sourceMappingURL=validate.d.ts.map

package/lib/typescript/module/config/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../../src/config/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,oBAAiB,CAAC;AAChF,OAAO,EAA8B,KAAK,gBAAgB,EAAE,MAAM,mBAAgB,CAAC;AAGnF,OAAO,EAAyB,KAAK,mBAAmB,EAAE,MAAM,wBAAqB,CAAC;AACtF,OAAO,KAAK,EAEX,SAAS,EACT,qBAAqB,EACrB,UAAU,EACV,WAAW,EACX,mBAAmB,EACnB,MAAM,YAAS,CAAC;AASjB,MAAM,WAAW,eAAe;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC9D,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,sEAAsE;IACtE,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAC,CAAC;IACrE;;;OAGG;IACH,QAAQ,CAAC,uBAAuB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9D,gDAAgD;IAChD,QAAQ,CAAC,cAAc,EAAE,qBAAqB,GAAG,SAAS,CAAC;IAC3D;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;CAChD;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,eAAe,GAAG,cAAc,CA+G1F"}

package/lib/typescript/module/core/adOriginatedReturn.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Ad-originated return detection (FR-128).
+ *
+ * This is the reason app-open belongs in the package rather than in the app.
+ * Every other app-open rule — when to show one, how often, on which screens — is
+ * policy the app owns. This one is not policy; it is a fact only the package
+ * holds. When a user dismisses a full-screen ad, or comes back from a browser an
+ * ad opened, the app sees an ordinary return to the foreground and has no way to
+ * tell it apart from any other. Showing an app-open ad on that return means
+ * showing an ad immediately after an ad, which is both a poor experience and the
+ * kind of thing store review notices.
+ *
+ * The package knows, because it holds the full-screen lock and it sees the click
+ * events. So it refuses, with a reason distinct from `busy` and `not_ready` so
+ * the app can tell what happened.
+ *
+ * **Bounded on both sides, deliberately.** Arming has to be tied to something
+ * that actually happened, and it has to expire:
+ *
+ *   - Armed when the provider reports a full-screen ad opened, or on a click —
+ *     that second case is a browser the ad opened, which is the only signal the
+ *     provider gives for it. Arming is deliberately not tied to the app
+ *     reporting that it went to the background; see `noteFullScreenShown`.
+ *   - Disarmed without firing if the app was away longer than
+ *     `AD_RETURN_MAX_AWAY_MS`. Someone who left, did something else, and came
+ *     back an hour later is not returning from an ad, and treating them as if
+ *     they were would refuse a legitimate show.
+ *   - Refusals last `AD_RETURN_GRACE_MS` after the return, then stop. The window
+ *     only needs to cover the moment right after the return, where an app-open
+ *     show would otherwise fire. A window that outlived that moment would start
+ *     refusing shows that have nothing to do with the ad.
+ *
+ * Three limits are worth stating plainly, because they are limits rather than
+ * defects and the documentation must not imply otherwise:
+ *
+ *   1. It cannot survive process death. If the OS kills the app while an ad is
+ *      on screen, the return is a cold start and nothing links it to the ad.
+ *   2. It depends on the app reporting `setAppActive` faithfully — an obligation
+ *      0.1.0 already imposes for staleness re-evaluation, not a new one.
+ *   3. A browser opened by an ad without a preceding click event is undetectable.
+ *
+ * Pure state. No listener, no timer — it is driven entirely by transitions the
+ * package already observes, which is why `dispose()` has nothing extra to
+ * release for it.
+ */
+export interface AdOriginatedTracker {
+    /** A full-screen ad is on screen, per the provider's own `opened` callback. */
+    noteFullScreenShown(nowMs: number): void;
+    /** Record an ad click — the only signal that an ad opened a browser. */
+    noteClick(nowMs: number): void;
+    /** The app went to the background. Kept for the click case's timing. */
+    noteBackground(nowMs: number): void;
+    /** The app came back. Decides whether this return was ad-originated. */
+    noteForeground(nowMs: number): void;
+    /** Whether an app-open show should be refused right now. */
+    isRefusing(nowMs: number): boolean;
+    /** Drops all state. For dispose, and for tests asserting a clean slate. */
+    reset(): void;
+}
+export declare function createAdOriginatedTracker(): AdOriginatedTracker;
+//# sourceMappingURL=adOriginatedReturn.d.ts.map

package/lib/typescript/module/core/adOriginatedReturn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adOriginatedReturn.d.ts","sourceRoot":"","sources":["../../../../src/core/adOriginatedReturn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAIH,MAAM,WAAW,mBAAmB;IACnC,+EAA+E;IAC/E,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,wEAAwE;IACxE,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,wEAAwE;IACxE,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,wEAAwE;IACxE,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,4DAA4D;IAC5D,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC,2EAA2E;IAC3E,KAAK,IAAI,IAAI,CAAC;CACd;AAED,wBAAgB,yBAAyB,IAAI,mBAAmB,CAsE/D"}

package/lib/typescript/module/core/adsInstance.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The ads instance — the public contract's implementation.
+ *
+ * Every guarantee the specification treats as a rule rather than a convention
+ * converges here, and none of it needs a device to prove:
+ *
+ *   FR-022  one native initialization, however many callers race
+ *   FR-017  no request before the privacy gate permits one
+ *   FR-011  no production ad unit outside production
+ *   FR-029  one in-flight provider request per placement
+ *   FR-030  exactly one full-screen ad, never a queue
+ *   FR-031  a consumed ad is never reused
+ *   FR-035  after dispose, a late callback updates nothing and emits nothing
+ *
+ * This file only composes. Each responsibility lives in `core/instance/` and
+ * takes the shared context (ADS-10): the gate, initialization and enablement,
+ * full-screen load, show, consent, and the banner host's internals.
+ *
+ * Nothing here imports the provider. It talks to the engine port, which the
+ * caller injects — the AdMob adapter in production, the fake in tests.
+ */
+import type { AdsConfig } from '../config/types.js';
+import type { AdsEngine } from '../engine/port.js';
+import type { AdsInstance, CreateAdsOptions } from './instance/types.js';
+export type { AdsInstance, ConsentApi, CreateAdsOptions, InitResult, LoadRefusal, LoadResult, PrivacyOptionsFormResult, PrivacyUpdateResult, ShowResult, ThrottledResult, } from './instance/types.js';
+export { getInternals, type InstanceInternals } from './instance/internals.js';
+/**
+ * The instance itself. The public `createAds` (src/index.ts) passes the AdMob
+ * adapter as `defaultEngine`: core/ never loads an adapter, so it stays testable
+ * in Node and the provider stays replaceable (ADS-14).
+ */
+export declare function createAds(config: AdsConfig, options?: CreateAdsOptions, defaultEngine?: () => AdsEngine): AdsInstance;
+//# sourceMappingURL=adsInstance.d.ts.map

package/lib/typescript/module/core/adsInstance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adsInstance.d.ts","sourceRoot":"","sources":["../../../../src/core/adsInstance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAgB,CAAC;AAQhD,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,qBAAkB,CAAC;AAEtE,YAAY,EACX,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,UAAU,EACV,wBAAwB,EACxB,mBAAmB,EACnB,UAAU,EACV,eAAe,GACf,MAAM,qBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,yBAAsB,CAAC;AAE5E;;;;GAIG;AACH,wBAAgB,SAAS,CACxB,MAAM,EAAE,SAAS,EACjB,OAAO,GAAE,gBAAqB,EAC9B,aAAa,GAAE,MAAM,SAA2B,GAC9C,WAAW,CAgFb"}

package/lib/typescript/module/core/consentFlow.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Consent orchestration and normalization (FR-101 – FR-110).
+ *
+ * This closes the most serious gap in 0.1.0. The package *consumed* a consent
+ * decision but nothing *produced* one, and the flow that produces it lives
+ * inside the very provider library the package promised an app would never have
+ * to import. So any app shipping to a consent-required region had to import the
+ * provider directly — breaking the package's central promise at exactly the
+ * point where it mattered most — and hand-write the same order-sensitive
+ * orchestration every other such app was also writing.
+ *
+ * What this module does **not** do is as load-bearing as what it does:
+ *
+ *   - It renders no consent UI. The form is the provider's (FR-103).
+ *   - It decides nothing about jurisdictions. Which regions require consent is
+ *     the provider's answer and the publisher's console configuration; the
+ *     package forwards it (FR-107).
+ *   - It never infers consent. An error, a cancellation, a dismissed form, a
+ *     network failure — all of them land on `error`, and `error` never carries
+ *     permission (FR-106). This is the invariant the whole module exists to
+ *     protect, because the failure it prevents is invisible: a request that
+ *     should not have happened looks exactly like one that should.
+ *
+ * Pure apart from the port calls it awaits. No React, no provider type crossing
+ * outward.
+ */
+import type { ConsentSnapshot, ConsentTestingOptions } from '../config/types.js';
+import { AdsError } from '../diagnostics/errors.js';
+import type { EngineConsentInfo, EngineConsentOptions } from '../engine/port.js';
+import type { ConsentGateInput } from './gates.js';
+export declare const INITIAL_CONSENT: ConsentSnapshot;
+/**
+ * Maps the engine's status onto the published one.
+ *
+ * `canRequestAds` is taken from the provider rather than derived from the
+ * status. The two are not the same question — a region can be `not_required`
+ * while the provider still withholds permission — and inventing the second
+ * answer from the first is how a package ends up requesting ads it should not.
+ */
+export declare function normalizeConsent(info: EngineConsentInfo): ConsentSnapshot;
+/**
+ * The snapshot for a failed flow.
+ *
+ * `canRequestAds` is hard-coded false rather than carried through from anywhere.
+ * There is no failure mode in which "the flow broke" should mean "go ahead", and
+ * making that structural rather than conditional means no future edit can
+ * accidentally reintroduce the inference.
+ *
+ * The privacy-options requirement is `unknown` for the same reason: a broken
+ * flow has no provider verdict to forward, and reporting `not_required` would be
+ * the package deciding the user has no right to change their mind (FR-150).
+ */
+export declare function consentFailure(error: AdsError): ConsentSnapshot;
+export declare function toConsentError(cause: unknown, message: string): AdsError;
+/**
+ * Projects a snapshot onto the consent gate's second input.
+ *
+ * Only `obtained` and `not_required` open it. `undetermined` and `required` are
+ * both "we do not have permission yet" and are reported as
+ * `consent_flow_required`; `error` gets its own reason so an app can tell a
+ * user who has not answered from a flow that broke.
+ */
+export declare function toGateInput(snapshot: ConsentSnapshot): ConsentGateInput;
+/**
+ * Builds the options for a consent information update.
+ *
+ * `testing` has already been stripped by config validation when the environment
+ * is production, so this function does not re-check. That is deliberate: the
+ * guarantee lives at one point rather than being re-asserted at each call site,
+ * which is the same reason the ad-unit substitution guarantee is provable
+ * (FR-113).
+ */
+export declare function buildConsentOptions(testing: ConsentTestingOptions | undefined, underAgeOfConsent: boolean | undefined, testDeviceIds: readonly string[]): EngineConsentOptions;
+/**
+ * One consent operation, with the never-infer rule applied to every exit.
+ *
+ * Every path out of here is either a normalized snapshot or a normalized error
+ * snapshot. Nothing throws, because a consent failure must not be able to block
+ * app startup or crash the host (FR-108).
+ */
+export declare function runConsentStep(step: () => Promise<EngineConsentInfo>, failureMessage: string): Promise<ConsentSnapshot>;
+/** Whether a form should be presented, per the provider's own report. */
+export declare function needsForm(snapshot: ConsentSnapshot): boolean;
+//# sourceMappingURL=consentFlow.d.ts.map

package/lib/typescript/module/core/consentFlow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consentFlow.d.ts","sourceRoot":"","sources":["../../../../src/core/consentFlow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAgB,qBAAqB,EAAE,MAAM,oBAAiB,CAAC;AAC5F,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAAuB,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,mBAAgB,CAAC;AAC9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAS,CAAC;AAEhD,eAAO,MAAM,eAAe,EAAE,eAM7B,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,eAAe,CAiBzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,eAAe,CAQ/D;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ,CAMxE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,gBAAgB,CAWvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,qBAAqB,GAAG,SAAS,EAC1C,iBAAiB,EAAE,OAAO,GAAG,SAAS,EACtC,aAAa,EAAE,SAAS,MAAM,EAAE,GAC9B,oBAAoB,CAMtB;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CACnC,IAAI,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,EACtC,cAAc,EAAE,MAAM,GACpB,OAAO,CAAC,eAAe,CAAC,CAM1B;AAED,yEAAyE;AACzE,wBAAgB,SAAS,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAI5D"}

package/lib/typescript/module/core/enablement.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Three-state enablement and the typed result of changing it (FR-114 – FR-125).
+ *
+ * 0.1.0 had a boolean, which forced an app selling an ad-removal tier to lie at
+ * startup. It does not yet know whether this user has paid — that answer arrives
+ * after a store sync — and both available answers are wrong: `true` flashes ads
+ * at someone who paid to never see them, `false` delays ads for everyone else
+ * and then runs into the silent re-enable trap below. The missing third state
+ * was a hole in the contract, not an omission in the app.
+ *
+ * The package still knows nothing about payments, entitlements, or why the app
+ * decided anything (FR-120). It only stops insisting the decision already exists
+ * at construction time.
+ *
+ * Pure — no provider, no React, no I/O.
+ */
+import type { Enablement, InitStatus, UnavailableReason } from '../config/types.js';
+/**
+ * Normalizes the configured value. `true`/`false` keep their exact 0.1.0
+ * meaning, which is what makes the widened config type additive (BC-003).
+ */
+export declare function toEnablement(value: boolean | 'undecided'): Enablement;
+/** Neither `disabled` nor `undecided` may reach the provider (FR-115). */
+export declare function permitsRequests(enablement: Enablement): boolean;
+/**
+ * The outcome of an enablement change.
+ *
+ * 0.1.0 returned `void`, which is the defect FR-122 supersedes. Re-enabling
+ * after a disable sent the init status back to `not_started`, so the app *had*
+ * to call `initialize()` again or every later load and show was refused — and
+ * nothing said so. Not the result, not the status, not the documentation. An app
+ * whose user's subscription lapsed would turn ads back on and silently show
+ * none.
+ */
+export type EnablementResult = 
+/**
+ * Returned to the status held before disabling, with zero provider calls.
+ * The common case: disabling never un-initializes the provider, so there is
+ * genuinely nothing to redo.
+ */
+{
+    readonly status: 'resumed';
+    readonly initStatus: InitStatus;
+}
+/**
+ * The instance never reached `ready`, privacy options changed, or the
+ * platform became unavailable. The caller must initialize; the package will
+ * not do it implicitly, because that would hide an asynchronous, billable
+ * operation behind a setter the caller may not be awaiting (FR-121).
+ */
+ | {
+    readonly status: 'requires_initialization';
+} | {
+    readonly status: 'disabled';
+} | {
+    readonly status: 'undecided';
+}
+/** The requested state was already the current one. No work, no event. */
+ | {
+    readonly status: 'unchanged';
+} | {
+    readonly status: 'unavailable';
+    readonly reason: UnavailableReason;
+};
+/**
+ * Whether re-enabling can resume, given what the instance was doing when it was
+ * turned off.
+ *
+ * Only `ready` resumes. Everything else — never started, still initializing,
+ * blocked, failed — has no completed initialization to return to, so claiming a
+ * resume would put the instance in a state it never actually reached.
+ */
+export declare function canResume(resumeTo: InitStatus | null): resumeTo is 'ready';
+//# sourceMappingURL=enablement.d.ts.map

package/lib/typescript/module/core/enablement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enablement.d.ts","sourceRoot":"","sources":["../../../../src/core/enablement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,oBAAiB,CAAC;AAEjF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,UAAU,CAKrE;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAE/D;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB;AAC3B;;;;GAIG;AACD;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;CAAE;AACjE;;;;;GAKG;GACD;IAAE,QAAQ,CAAC,MAAM,EAAE,yBAAyB,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE;AAClC,0EAA0E;GACxE;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAChC;IAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAE1E;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI,GAAG,QAAQ,IAAI,OAAO,CAE1E"}

package/lib/typescript/module/core/fullScreenLock.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The single full-screen lock (FR-030).
+ *
+ * One token per instance, not per placement, because the constraint is about the
+ * screen rather than about any particular ad: two full-screen ads stacked on top
+ * of each other is a broken app regardless of which placements produced them.
+ *
+ * **There is no queue.** A refused show is refused, and the caller is told so
+ * immediately. Queueing would mean an ad opening at a moment the app never
+ * chose — seconds later, on a different screen, after the user moved on — which
+ * is exactly the behavior FR-045 forbids the package from deciding on its own.
+ */
+export interface FullScreenLock {
+    /** Takes the lock, or returns false if another full-screen ad holds it. */
+    acquire(placementKey: string): boolean;
+    /** Releases only if this placement holds it; a stale release is a no-op. */
+    release(placementKey: string): void;
+    /** Whichever placement currently holds it, if any. */
+    holder(): string | null;
+    isHeld(): boolean;
+    /** Drops the lock unconditionally. For dispose only. */
+    reset(): void;
+}
+export declare function createFullScreenLock(): FullScreenLock;
+//# sourceMappingURL=fullScreenLock.d.ts.map

package/lib/typescript/module/core/fullScreenLock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fullScreenLock.d.ts","sourceRoot":"","sources":["../../../../src/core/fullScreenLock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,cAAc;IAC9B,2EAA2E;IAC3E,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;IACvC,4EAA4E;IAC5E,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,sDAAsD;IACtD,MAAM,IAAI,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,IAAI,OAAO,CAAC;IAClB,wDAAwD;IACxD,KAAK,IAAI,IAAI,CAAC;CACd;AAED,wBAAgB,oBAAoB,IAAI,cAAc,CA4BrD"}