@chipmobilesdk/rn-ads 0.7.0 → 0.8.0

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

@@ -0,0 +1,76 @@
+/**
+ * The one place that decides why a request was refused (FR-140, FR-141).
+ *
+ * After 0.2.0 there are three independent ways to be blocked — platform
+ * availability, the app's three-state enable flag, and consent — and they can be
+ * closed in any combination. A precedence spread across four call sites is not a
+ * precedence; it is four coincidences that currently agree. So every refusal
+ * path in the package routes through `evaluateGates` and nothing else compares
+ * gate state.
+ *
+ * **The order is availability, then enablement, then consent — most immovable
+ * first.** Two reasons, and they agree:
+ *
+ * 1. It is what 0.1.0 already did. `initMachine`'s BLOCK transition is refused
+ *    outright when the status is `disabled` or `unavailable`, so consent was
+ *    already the weakest of the three. Any other order would change observable
+ *    behavior for a consumer who configured nothing new.
+ * 2. It is the most useful order for whoever is debugging. An unsupported
+ *    platform makes the other two unfixable, so reporting "consent required" on
+ *    a platform that can never serve an ad sends a developer off to build a flow
+ *    that will never help. Reporting `unavailable` to an app that has also
+ *    disabled ads costs nothing — that app was not going to show an ad either
+ *    way.
+ *
+ * The accepted cost is that an app which *deliberately* disabled ads on an
+ * unsupported platform is told about the platform rather than about its own
+ * switch. That is fine: neither answer changes what the app does next.
+ *
+ * Pure. No provider, no React, no I/O — which is what lets the full combination
+ * table be a unit test rather than an integration one.
+ */
+import type { Enablement, PrivacyBlockReason, UnavailableReason } from '../config/types.js';
+/** What the consent flow contributes, or `null` when the app never opted in. */
+export type ConsentGateInput = {
+    readonly permitted: true;
+} | {
+    readonly permitted: false;
+    readonly reason: 'consent_flow_required' | 'consent_flow_error';
+} | null;
+export interface GateInput {
+    readonly available: {
+        readonly ok: true;
+    } | {
+        readonly ok: false;
+        readonly reason: UnavailableReason;
+    };
+    readonly enablement: Enablement;
+    /** The app's own gate, from `PrivacyOptions.canRequestAds`. */
+    readonly appGate: {
+        readonly permitted: true;
+    } | {
+        readonly permitted: false;
+        readonly reason: PrivacyBlockReason;
+    };
+    /** The package's consent flow. `null` when unused — then the app's gate alone decides. */
+    readonly consentGate: ConsentGateInput;
+}
+export type GateDecision = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly kind: 'unavailable';
+    readonly reason: UnavailableReason;
+} | {
+    readonly allowed: false;
+    readonly kind: 'disabled';
+} | {
+    readonly allowed: false;
+    readonly kind: 'undecided';
+} | {
+    readonly allowed: false;
+    readonly kind: 'blocked';
+    readonly reason: PrivacyBlockReason;
+};
+export declare function evaluateGates(input: GateInput): GateDecision;
+//# sourceMappingURL=gates.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../../../../src/core/gates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,oBAAiB,CAAC;AAEzF,gFAAgF;AAChF,MAAM,MAAM,gBAAgB,GACzB;IAAE,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,uBAAuB,GAAG,oBAAoB,CAAA;CAAE,GAC9F,IAAI,CAAC;AAER,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,SAAS,EACjB;QAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;KAAE,CAAC;IACpF,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EACb;QAAE,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;KAAE,GAC5B;QAAE,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;KAAE,CAAC;IACtE,0FAA0F;IAC1F,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;CACvC;AAED,MAAM,MAAM,YAAY,GACrB;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,GAC7F;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAE9F,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,YAAY,CAkC5D"}

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

@@ -0,0 +1,66 @@
+/**
+ * Initialization state machine (FR-022 – FR-025).
+ *
+ * Pure and synchronous: it decides what a transition means; the instance
+ * performs the I/O. That split is what makes every rule in data-model.md §3.1
+ * testable without a provider.
+ *
+ * The load-bearing invariant is idempotence. Three consumers calling
+ * `initialize()` at once must produce exactly one native initialization and
+ * three identical results (SC-005) — the instance holds one in-flight promise,
+ * and this machine refuses to leave `initializing` for anything but a terminal
+ * outcome.
+ */
+import type { InitStatus, PrivacyBlockReason, UnavailableReason } from '../config/types.js';
+import type { AdsError } from '../diagnostics/errors.js';
+export type InitEvent = {
+    readonly type: 'START';
+} | {
+    readonly type: 'BLOCK';
+    readonly reason: PrivacyBlockReason;
+} | {
+    readonly type: 'UNAVAILABLE';
+    readonly reason: UnavailableReason;
+} | {
+    readonly type: 'DISABLE';
+} | {
+    readonly type: 'UNDECIDE';
+} | {
+    readonly type: 'ENABLE';
+} | {
+    readonly type: 'SUCCEED';
+}
+/**
+ * Back to `ready` with no native call, because the provider was initialized
+ * earlier and nothing has torn it down since (FR-154). The instance decides
+ * whether that holds; this machine only refuses to resume from a state a
+ * fresh start could not leave either.
+ */
+ | {
+    readonly type: 'RESUME';
+} | {
+    readonly type: 'FAIL';
+    readonly error: AdsError;
+};
+export interface InitSnapshot {
+    readonly status: InitStatus;
+    readonly blockReason: PrivacyBlockReason | null;
+    readonly unavailableReason: UnavailableReason | null;
+    readonly error: AdsError | null;
+    /**
+     * The status held when ads were switched off, so re-enabling can return to
+     * it instead of silently dropping to `not_started`.
+     *
+     * 0.1.0's `ENABLE` sent a disabled instance to `not_started`, which meant the
+     * app had to call `initialize()` again or every later load and show was
+     * refused — and nothing said so. Remembering one value is the whole fix
+     * (FR-121).
+     */
+    readonly resumeTo: InitStatus | null;
+}
+export declare const initialInit: InitSnapshot;
+export declare function canStart(status: InitStatus): boolean;
+/** Only `ready` may issue requests. Everything else is a refusal with a reason. */
+export declare function canRequest(status: InitStatus): boolean;
+export declare function initReducer(state: InitSnapshot, event: InitEvent): InitSnapshot;
+//# sourceMappingURL=initMachine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"initMachine.d.ts","sourceRoot":"","sources":["../../../../src/core/initMachine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,oBAAiB,CAAC;AACzF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAAuB,CAAC;AAEtD,MAAM,MAAM,SAAS,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE;AAC9B;;;;;GAKG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAChD,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACrD,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IAChC;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI,CAAC;CACrC;AAED,eAAO,MAAM,WAAW,EAAE,YAMzB,CAAC;AA+BF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAEpD;AAED,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAEtD;AAkBD,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,GAAG,YAAY,CAyE/E"}

package/lib/typescript/module/core/instance/consent.d.ts

@@ -0,0 +1,4 @@
+import type { InstanceContext } from './context.js';
+import type { ConsentApi } from './types.js';
+export declare function createConsentApi(context: InstanceContext, reevaluate: () => Promise<void>): ConsentApi;
+//# sourceMappingURL=consent.d.ts.map

package/lib/typescript/module/core/instance/consent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent.d.ts","sourceRoot":"","sources":["../../../../../src/core/instance/consent.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAW,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAS,CAAC;AAE1C,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,eAAe,EACxB,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAC7B,UAAU,CA0IZ"}

package/lib/typescript/module/core/instance/context.d.ts

@@ -0,0 +1,118 @@
+/**
+ * What every part of an ads instance shares (ADS-10).
+ *
+ * 0.5.0 kept all of this as `let` bindings inside one 1,500-line closure, and
+ * each path that closed a gate re-implemented its own teardown — which is how
+ * ADS-01, ADS-02 and ADS-04 happened. Here the state is one object, the
+ * placement runtimes are one map, and the helpers that change them are defined
+ * once. The controllers (gate, init, load, show, consent, banner) each take this
+ * context and nothing else.
+ */
+import { type ListenerSet } from '@chipmobilesdk/rn-core';
+import { type AdFormat, type AdsConfig, type ConsentSnapshot, type Enablement, type InitStatus, type PlacementDefinition, type PlacementState, type PrivacyOptions, type Unsubscribe } from '../../config/types.js';
+import { type ResolvedConfig } from '../../config/validate.js';
+import { type CorrelationIssuer } from '../../diagnostics/correlation.js';
+import { type AdEventEmitter } from '../../diagnostics/events.js';
+import type { AdsEngine, EngineAdHandle } from '../../engine/port.js';
+import { type AdOriginatedTracker } from '../adOriginatedReturn.js';
+import { type FullScreenLock } from '../fullScreenLock.js';
+import { type InitSnapshot } from '../initMachine.js';
+import { placementReducer, type PlacementSnapshot } from '../placementMachine.js';
+import { type RequestThrottle } from '../requestThrottle.js';
+import type { RewardedSession } from '../rewardedSession.js';
+import { type TimerSet } from '../timers.js';
+import type { CreateAdsOptions, InitResult, LoadRefusal, LoadResult } from './types.js';
+export interface PlacementRuntime {
+    snapshot: PlacementSnapshot;
+    /**
+     * The cycle's correlation id, held here rather than read from the snapshot:
+     * the reducer resets the snapshot on dismissal, and events emitted around
+     * that transition must still carry the id of the cycle they belong to.
+     */
+    correlationId: string | null;
+    /**
+     * Whether this cycle already reported a dismissal. Format-independent — the
+     * rewarded session guards its own, but interstitials need the same guard and
+     * would otherwise report a repeated provider callback twice.
+     */
+    dismissed: boolean;
+    handle: EngineAdHandle | null;
+    unsubscribeEngine: Unsubscribe | null;
+    inFlightLoad: Promise<LoadResult> | null;
+    /**
+     * Settles the in-flight load with a given result. Only a gate closing uses it
+     * (FR-153): the caller awaiting `load()` is told the refusal instead of
+     * waiting on a request that has been abandoned.
+     */
+    abortLoad: ((result: LoadResult) => void) | null;
+    cancelLoadTimer: Unsubscribe | null;
+    cancelShowTimer: Unsubscribe | null;
+    rewarded: RewardedSession | null;
+    listeners: ListenerSet<[PlacementState]>;
+    /** Retries already spent in this load cycle. Reset when a new cycle starts. */
+    retryAttempts: number;
+    /** Cancels a scheduled retry. Called by disable, undecided, and dispose. */
+    cancelRetry: Unsubscribe | null;
+}
+/** Everything about the instance that changes after creation. */
+export interface InstanceState {
+    init: InitSnapshot;
+    enablement: Enablement;
+    appActive: boolean;
+    consent: ConsentSnapshot;
+    /** Whether the app ever used the consent flow; until then the gate ignores it (FR-102). */
+    consentStarted: boolean;
+    /**
+     * Consent forms currently on screen. A count rather than a flag because
+     * `showFormIfRequired` has never refused a concurrent call; only the privacy
+     * options form reads it, to report `busy`.
+     */
+    consentFormsOpen: number;
+    privacyOptionsFormOpen: boolean;
+    /**
+     * Whether the provider has been natively initialized, ever, by this instance.
+     *
+     * Tracked apart from the init status because the status can leave `ready` —
+     * a withdrawn consent moves it to `blocked` — while the native SDK stays
+     * initialized. Re-granting must resume, not initialize again (FR-022, FR-154).
+     */
+    providerInitialized: boolean;
+    undecidedWarned: boolean;
+    cancelUndecidedTimer: Unsubscribe | null;
+    appliedPrivacy: PrivacyOptions | null;
+    currentPrivacy: PrivacyOptions | null;
+    inFlightInit: Promise<InitResult> | null;
+    disposed: boolean;
+    warnedSubstitution: boolean;
+}
+export interface InstanceContext {
+    readonly resolved: ResolvedConfig;
+    readonly engine: AdsEngine;
+    readonly now: () => number;
+    readonly events: AdEventEmitter;
+    readonly correlation: CorrelationIssuer;
+    /** FR-140. Account safety, not product policy — see core/requestThrottle.ts. */
+    readonly requestThrottle: RequestThrottle;
+    readonly timers: TimerSet;
+    readonly lock: FullScreenLock;
+    readonly adReturn: AdOriginatedTracker;
+    readonly state: InstanceState;
+    readonly placements: ReadonlyMap<string, PlacementRuntime>;
+    readonly statusListeners: ListenerSet<[InitStatus]>;
+    readonly consentListeners: ListenerSet<[ConsentSnapshot]>;
+    /** A placement's runtime and definition together, or null for an unknown key (ADS-18). */
+    placement(key: string): {
+        runtime: PlacementRuntime;
+        definition: PlacementDefinition;
+    } | null;
+    setInit(next: InitSnapshot): void;
+    setPlacement(key: string, next: PlacementSnapshot): void;
+    dispatchPlacement(key: string, event: Parameters<typeof placementReducer>[1]): void;
+    setConsent(next: ConsentSnapshot): void;
+    releasePlacementResources(key: string): void;
+    emitRefusal(operation: 'initialize' | 'load' | 'show', result: LoadRefusal, placementKey?: string, format?: AdFormat): void;
+}
+export declare function createInstanceContext(config: AdsConfig, options: CreateAdsOptions, defaultEngine: () => AdsEngine): InstanceContext;
+/** App-open expires on its own, shorter window (FR-130). */
+export declare function validityFor(context: InstanceContext, format: AdFormat): number;
+//# sourceMappingURL=context.d.ts.map

package/lib/typescript/module/core/instance/context.d.ts.map

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

package/lib/typescript/module/core/instance/gate.d.ts

@@ -0,0 +1,38 @@
+import { type GateDecision } from '../gates.js';
+import type { InstanceContext } from './context.js';
+import type { LoadRefusal } from './types.js';
+/**
+ * Assembles the gate's inputs and defers the precedence entirely to
+ * `evaluateGates`: availability, then enablement, then the app's privacy input,
+ * then the consent flow. Nothing else compares gate state.
+ *
+ * The consent flow contributes `null` until the app opts into it, which is what
+ * makes FR-102 structural: with no flow started the gate sees only the app's
+ * own input and behaves exactly as 0.1.0 did.
+ */
+export declare function currentGate(context: InstanceContext): GateDecision;
+/** Maps a closed gate onto the refusal shape load, show, and the banner share. */
+export declare function refusalFor(decision: Extract<GateDecision, {
+    allowed: false;
+}>): LoadRefusal;
+/** The refusal that applies now, or null when a request may go ahead. */
+export declare function gateRefusal(context: InstanceContext): LoadRefusal | null;
+/** Cancels every pending retry, everywhere (FR-137). */
+export declare function cancelAllRetries(context: InstanceContext): void;
+/**
+ * The one teardown for a gate that closed to `refusal`: retries cancelled,
+ * placements halted, and the init status moved to match.
+ */
+export declare function closeGate(context: InstanceContext, refusal: Exclude<LoadRefusal, {
+    status: 'unavailable';
+}>): void;
+/**
+ * Warns once if the app leaves `undecided` unresolved (FR-119).
+ *
+ * Once, not repeatedly: a warning that fires every ten seconds becomes noise.
+ * And it only warns — resolving the state would mean guessing the business
+ * decision FR-120 forbids the package from knowing.
+ */
+export declare function armUndecidedWarning(context: InstanceContext): void;
+export declare function disarmUndecidedWarning(context: InstanceContext): void;
+//# sourceMappingURL=gate.d.ts.map

package/lib/typescript/module/core/instance/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../../../../src/core/instance/gate.ts"],"names":[],"mappings":"AAWA,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,aAAU,CAAC;AAG5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAW,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAS,CAAC;AAE3C;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,YAAY,CASlE;AAED,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,QAAQ,EAAE,OAAO,CAAC,YAAY,EAAE;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,CAAC,GAAG,WAAW,CAW3F;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,WAAW,GAAG,IAAI,CAGxE;AAED,wDAAwD;AACxD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAK/D;AA4BD;;;GAGG;AACH,wBAAgB,SAAS,CACxB,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,OAAO,CAAC,WAAW,EAAE;IAAE,MAAM,EAAE,aAAa,CAAA;CAAE,CAAC,GACtD,IAAI,CAcN;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAoBlE;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAGrE"}

package/lib/typescript/module/core/instance/init.d.ts

@@ -0,0 +1,13 @@
+import { type EnablementResult } from '../enablement.js';
+import type { Enablement, PrivacyOptions } from '../../config/types.js';
+import type { InstanceContext } from './context.js';
+import type { InitResult, PrivacyUpdateResult } from './types.js';
+export interface InitController {
+    initialize(privacy: PrivacyOptions): Promise<InitResult>;
+    updatePrivacy(privacy: PrivacyOptions): Promise<PrivacyUpdateResult>;
+    setEnablement(next: Enablement): EnablementResult;
+    /** Applies a consent outcome to the gate, initializing at most once (FR-105). */
+    reevaluateAfterConsent(): Promise<void>;
+}
+export declare function createInitController(context: InstanceContext): InitController;
+//# sourceMappingURL=init.d.ts.map

package/lib/typescript/module/core/instance/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../../../src/core/instance/init.ts"],"names":[],"mappings":"AASA,OAAO,EAAa,KAAK,gBAAgB,EAAE,MAAM,kBAAe,CAAC;AAGjE,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,uBAAoB,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAW,CAAC;AASjD,OAAO,KAAK,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,YAAS,CAAC;AAE/D,MAAM,WAAW,cAAc;IAC9B,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACzD,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACrE,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,gBAAgB,CAAC;IAClD,iFAAiF;IACjF,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,eAAe,GAAG,cAAc,CAqO7E"}

package/lib/typescript/module/core/instance/internals.d.ts

@@ -0,0 +1,60 @@
+/**
+ * What `AdsBanner` needs from an instance, held off the public type (ADS-13).
+ *
+ * 0.5.0 exposed this as `AdsInstance.internals`, so any consumer could emit an
+ * `impression` or a `reward_earned` into the stream used for revenue
+ * reconciliation, and every change here was a breaking type change. It now
+ * lives in a WeakMap keyed by the instance: the banner host looks it up, and an
+ * instance an app wrote by hand simply has none.
+ */
+import type { PlacementState } from '../../config/types.js';
+import type { AdEvent } from '../../diagnostics/events.js';
+import type { EngineBanner } from '../../engine/port.js';
+import type { InstanceContext } from './context.js';
+import type { AdsInstance, LoadResult, ThrottledResult } from './types.js';
+export interface InstanceInternals {
+    /**
+     * Whether a banner for this placement may request now, and with what. Pure:
+     * it mints nothing, so the host can call it during render (ADS-20).
+     */
+    resolveBanner(placementKey: string): {
+        readonly ok: true;
+        readonly adUnitId: string;
+        /** Current at resolution time, so a banner request honors `updatePrivacy`. */
+        readonly personalizedAds: boolean;
+    } | {
+        readonly ok: false;
+        readonly result: LoadResult;
+    };
+    /**
+     * Takes the throttle slot for a banner mount (FR-140).
+     *
+     * Called during render, immediately before the provider component mounts:
+     * that component requests as part of the same render, so an effect would be
+     * too late. Idempotent for one `token`, so a render that runs twice charges
+     * one slot. Emits nothing and sets no state; the host reports a refusal from
+     * its effect.
+     */
+    commitBannerRequest(placementKey: string, token: string): ThrottledResult | null;
+    /** The configured floor for a placement, so the host can report the cause. */
+    throttleFloorFor(placementKey: string): number;
+    /** The engine's banner when it can render here, or null (ADS-12). */
+    banner(): EngineBanner | null;
+    emit(event: AdEvent): void;
+    setPlacementState(key: string, state: PlacementState): void;
+    isReady(): boolean;
+    nextCorrelationId(): string;
+    /** The instance's clock, so banner events and full-screen events agree (ADS-20). */
+    now(): number;
+    /**
+     * Runs `task` after `delayMs` on the instance's timers, so a test clock drives
+     * it and dispose() cancels it. Returns a cancel.
+     */
+    schedule(delayMs: number, task: () => void): () => void;
+    timerCount(): number;
+}
+/** The banner host's view of an instance `createAds` made; null for any other. */
+export declare function getInternals(instance: AdsInstance): InstanceInternals | null;
+export declare function attachInternals(instance: AdsInstance, internals: InstanceInternals): void;
+export declare function createInternals(context: InstanceContext): InstanceInternals;
+//# sourceMappingURL=internals.d.ts.map

package/lib/typescript/module/core/instance/internals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internals.d.ts","sourceRoot":"","sources":["../../../../../src/core/instance/internals.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAoB,CAAC;AAEzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,6BAA0B,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAmB,CAAC;AAItD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAW,CAAC;AAEjD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAS,CAAC;AAExE,MAAM,WAAW,iBAAiB;IACjC;;;OAGG;IACH,aAAa,CAAC,YAAY,EAAE,MAAM,GAC/B;QACA,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;QAClB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,8EAA8E;QAC9E,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;KACjC,GACD;QAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;KAAE,CAAC;IACvD;;;;;;;;OAQG;IACH,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAAC;IACjF,8EAA8E;IAC9E,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/C,qEAAqE;IACrE,MAAM,IAAI,YAAY,GAAG,IAAI,CAAC;IAC9B,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC3B,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5D,OAAO,IAAI,OAAO,CAAC;IACnB,iBAAiB,IAAI,MAAM,CAAC;IAC5B,oFAAoF;IACpF,GAAG,IAAI,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IACxD,UAAU,IAAI,MAAM,CAAC;CACrB;AAID,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,WAAW,GAAG,iBAAiB,GAAG,IAAI,CAE5E;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,iBAAiB,GAAG,IAAI,CAEzF;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,iBAAiB,CAiE3E"}

package/lib/typescript/module/core/instance/load.d.ts

@@ -0,0 +1,9 @@
+import type { InstanceContext } from './context.js';
+import type { LoadResult } from './types.js';
+export declare function unknownPlacement(context: InstanceContext, placementKey: string, operation: 'load' | 'show'): LoadResult & {
+    status: 'failed';
+};
+export declare function createLoader(context: InstanceContext): {
+    load(placementKey: string): Promise<LoadResult>;
+};
+//# sourceMappingURL=load.d.ts.map

package/lib/typescript/module/core/instance/load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../../../../src/core/instance/load.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAW,CAAC;AAEjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAS,CAAC;AAE1C,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAAG,MAAM,GACxB,UAAU,GAAG;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,CASnC;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,eAAe,GAAG;IACvD,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAChD,CAsXA"}

package/lib/typescript/module/core/instance/show.d.ts

@@ -0,0 +1,7 @@
+import { type InstanceContext } from './context.js';
+import type { ShowResult } from './types.js';
+export declare function createShower(context: InstanceContext): {
+    show(placementKey: string): Promise<ShowResult>;
+    setAppActive(active: boolean): void;
+};
+//# sourceMappingURL=show.d.ts.map

package/lib/typescript/module/core/instance/show.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"show.d.ts","sourceRoot":"","sources":["../../../../../src/core/instance/show.ts"],"names":[],"mappings":"AASA,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,cAAW,CAAC;AAG9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAS,CAAC;AAE1C,wBAAgB,YAAY,CAAC,OAAO,EAAE,eAAe,GAAG;IACvD,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAChD,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CACpC,CAwLA"}