@chipmobilesdk/rn-ads 0.6.0 → 0.8.0

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

@@ -0,0 +1,240 @@
+/**
+ * The ads instance's public contract: what `createAds` returns and what each
+ * operation reports. Implementation lives beside this file, one module per
+ * responsibility (ADS-10).
+ */
+import type { AdsError } from '../../diagnostics/errors.js';
+import type { ConsentSnapshot, Enablement, InitStatus, PlacementState, PrivacyBlockReason, PrivacyOptions, UnavailableReason, Unsubscribe } from '../../config/types.js';
+import type { AdEventListener } from '../../diagnostics/events.js';
+import type { AdsEngine } from '../../engine/port.js';
+import type { EnablementResult } from '../enablement.js';
+import type { Scheduler } from '../timers.js';
+export type InitResult = {
+    readonly status: 'ready';
+} | {
+    readonly status: 'blocked';
+    readonly reason: PrivacyBlockReason;
+} | {
+    readonly status: 'disabled';
+}
+/** The app has not decided whether ads are on. Nothing was requested (FR-115). */
+ | {
+    readonly status: 'undecided';
+} | {
+    readonly status: 'unavailable';
+    readonly reason: UnavailableReason;
+} | {
+    readonly status: 'failed';
+    readonly error: AdsError;
+};
+export type PrivacyUpdateResult = {
+    readonly status: 'applied';
+} | {
+    readonly status: 'blocked';
+    readonly reason: PrivacyBlockReason;
+} | {
+    readonly status: 'requires_reinitialization';
+} | {
+    readonly status: 'disabled';
+} | {
+    readonly status: 'undecided';
+} | {
+    readonly status: 'unavailable';
+    readonly reason: UnavailableReason;
+}
+/**
+ * The initialization this update triggered failed (added in 0.5.0). Before,
+ * it was reported as `applied`, so the app never retried and no ad ever
+ * showed, with nothing to say why.
+ */
+ | {
+    readonly status: 'failed';
+    readonly error: AdsError;
+};
+export type LoadResult = {
+    readonly status: 'loaded';
+    readonly correlationId: string;
+} | {
+    readonly status: 'disabled';
+} | {
+    readonly status: 'undecided';
+} | {
+    readonly status: 'blocked';
+    readonly reason: PrivacyBlockReason;
+} | {
+    readonly status: 'unavailable';
+    readonly reason: UnavailableReason;
+} | {
+    readonly status: 'no_fill';
+}
+/**
+ * Refused by the per-placement request throttle (FR-140), added in 0.3.0.
+ *
+ * Nothing was requested and nothing is broken — this placement asked too
+ * recently. Distinct from `no_fill` on purpose: no-fill means the network had
+ * nothing to give, this means we did not ask. An app that treats them the same
+ * will misdiagnose the first time a banner goes quiet.
+ */
+ | ThrottledResult | {
+    readonly status: 'timeout';
+} | {
+    readonly status: 'failed';
+    readonly error: AdsError;
+};
+export interface ThrottledResult {
+    readonly status: 'throttled';
+    readonly retryAfterMs: number;
+}
+/** A gate refusal: what a load gets when it may not ask at all. */
+export type LoadRefusal = Extract<LoadResult, {
+    status: 'disabled' | 'undecided' | 'blocked' | 'unavailable';
+}>;
+export type ShowResult = {
+    readonly status: 'shown';
+    readonly correlationId: string;
+} | {
+    readonly status: 'not_ready';
+} | {
+    readonly status: 'busy';
+} | {
+    readonly status: 'consumed';
+} | {
+    readonly status: 'app_inactive';
+}
+/**
+ * The user came back to the app from an ad, or from a browser an ad opened,
+ * so an app-open ad would be an ad immediately after an ad. Distinct from
+ * `busy` and `not_ready` because the app cannot detect this itself and
+ * therefore cannot infer it from either of those (FR-128).
+ */
+ | {
+    readonly status: 'ad_originated_return';
+} | {
+    readonly status: 'disabled';
+} | {
+    readonly status: 'undecided';
+} | {
+    readonly status: 'blocked';
+    readonly reason: PrivacyBlockReason;
+} | {
+    readonly status: 'unavailable';
+    readonly reason: UnavailableReason;
+} | {
+    readonly status: 'timeout';
+} | {
+    readonly status: 'failed';
+    readonly error: AdsError;
+};
+/**
+ * What `consent.showPrivacyOptionsForm()` reports (FR-151), added in 0.4.0.
+ *
+ * Every refusal is its own member, so an app can tell "there is nothing to
+ * offer here" from "you asked too early" from "it broke" without parsing an
+ * error. None of them throws.
+ */
+export type PrivacyOptionsFormResult = 
+/**
+ * The provider's form was presented and has closed. `consent` is the state it
+ * left behind, already applied to the gate. A user who closed the form without
+ * changing anything lands here too, with the state they already had.
+ */
+{
+    readonly status: 'shown';
+    readonly consent: ConsentSnapshot;
+}
+/** The provider does not require privacy options here. Nothing was presented. */
+ | {
+    readonly status: 'not_required';
+}
+/**
+ * The requirement is not known yet: no successful `requestInfoUpdate()` since
+ * the instance was created or reset, or the last one failed. Nothing was
+ * presented.
+ */
+ | {
+    readonly status: 'info_update_required';
+}
+/** A consent form is already on screen. Nothing was presented. */
+ | {
+    readonly status: 'busy';
+}
+/**
+ * The form could not be presented or failed while open. The consent state is
+ * whatever the provider reports it still holds, and never a new grant.
+ */
+ | {
+    readonly status: 'failed';
+    readonly error: AdsError;
+} | {
+    readonly status: 'unavailable';
+    readonly reason: UnavailableReason;
+};
+/**
+ * The optional consent capability (FR-101).
+ *
+ * Grouped under its own namespace rather than flattened onto the instance so
+ * that FR-102's optionality stays legible: an app that never touches
+ * `ads.consent` never starts a flow. Five loose methods on the instance would
+ * invite the assumption that they are part of the normal path.
+ */
+export interface ConsentApi {
+    /** Refreshes consent information from the provider. */
+    requestInfoUpdate(): Promise<ConsentSnapshot>;
+    /** Presents the provider's form if one is required. Renders nothing itself. */
+    showFormIfRequired(): Promise<ConsentSnapshot>;
+    /**
+     * Presents the provider's privacy options form, so a user can change an
+     * answer already given (FR-151). Added in 0.4.0.
+     *
+     * Offer it when `getState().privacyOptionsRequirement` is `required`. Where
+     * the entry point lives, and what it says, stay the app's. The outcome feeds
+     * the privacy gate by itself, exactly as `showFormIfRequired` does.
+     */
+    showPrivacyOptionsForm(): Promise<PrivacyOptionsFormResult>;
+    getState(): ConsentSnapshot;
+    subscribe(listener: (snapshot: ConsentSnapshot) => void): Unsubscribe;
+    /** Clears the stored decision. Inert in production (FR-113). */
+    reset(): Promise<void>;
+}
+export interface AdsInstance {
+    initialize(privacy: PrivacyOptions): Promise<InitResult>;
+    updatePrivacy(privacy: PrivacyOptions): Promise<PrivacyUpdateResult>;
+    /**
+     * Turns ads on or off. Returns a result rather than `void` (FR-122).
+     *
+     * 0.1.0 returned nothing, which meant an app re-enabling ads after a lapsed
+     * subscription had no way to learn that it also had to re-initialize — and
+     * every load and show after that was refused in silence.
+     */
+    setEnabled(enabled: boolean): EnablementResult;
+    /** The same, including the third state the app has not resolved yet. */
+    setEnablement(next: Enablement): EnablementResult;
+    setAppActive(active: boolean): void;
+    readonly consent: ConsentApi;
+    getStatus(): InitStatus;
+    subscribeStatus(listener: (status: InitStatus) => void): Unsubscribe;
+    load(placementKey: string): Promise<LoadResult>;
+    show(placementKey: string): Promise<ShowResult>;
+    getPlacementState(placementKey: string): PlacementState;
+    subscribePlacement(key: string, listener: (state: PlacementState) => void): Unsubscribe;
+    subscribeEvents(listener: AdEventListener): Unsubscribe;
+    /** FR-011a — substitution is observable state, not only a log line. */
+    getSubstitutedPlacements(): readonly string[];
+    /** FR-113 — the same treatment for consent tools dropped in production. */
+    getIgnoredConsentTools(): readonly string[];
+    dispose(): void;
+}
+export interface CreateAdsOptions {
+    /** Injected in tests; the AdMob adapter is the default in production. */
+    readonly engine?: AdsEngine;
+    /** Injected so the FR-012 rule is testable without touching a global. */
+    readonly isDevBuild?: boolean;
+    readonly now?: () => number;
+    /**
+     * Injected so retry backoff, app-open expiry, and the undecided warning can
+     * be driven by a test clock instead of by waiting. Production uses real
+     * timers.
+     */
+    readonly scheduler?: Scheduler;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

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

@@ -0,0 +1,55 @@
+/**
+ * Per-placement lifecycle (FR-026 – FR-031, FR-034).
+ *
+ * Pure and synchronous, per data-model.md §3.2. Two variants share one reducer:
+ *
+ *   full-screen — load, show once, become `consumed`, reload before the next show
+ *   banner      — continuous; it renders and may refresh, and never reaches
+ *                 `consumed`, because a banner is not a single-use resource
+ *
+ * Staleness is handled here rather than at the show site so that a stale ad can
+ * never be *reported* ready either — a consumer that renders a "Watch ad" button
+ * from `state === 'ready'` would otherwise offer a button that fails on tap.
+ */
+import type { AdFormat, PlacementState, UnavailableReason } from '../config/types.js';
+import type { AdsError } from '../diagnostics/errors.js';
+export type PlacementEvent = {
+    readonly type: 'LOAD';
+} | {
+    readonly type: 'LOADED';
+    readonly atMs: number;
+} | {
+    readonly type: 'LOAD_FAILED';
+    readonly error: AdsError;
+} | {
+    readonly type: 'SHOW';
+} | {
+    readonly type: 'SHOW_FAILED';
+    readonly error: AdsError;
+} | {
+    readonly type: 'DISMISSED';
+} | {
+    readonly type: 'EXPIRE';
+} | {
+    readonly type: 'UNAVAILABLE';
+    readonly reason: UnavailableReason;
+} | {
+    readonly type: 'RESET';
+};
+export interface PlacementSnapshot {
+    readonly state: PlacementState;
+    readonly loadedAtMs: number | null;
+    readonly error: AdsError | null;
+    readonly correlationId: string | null;
+}
+export declare const initialPlacement: PlacementSnapshot;
+/**
+ * A load is only legal from a settled state; `loading` is where FR-029 bites.
+ * `throttled` is settled too: it records that the last request was refused, and
+ * the throttle itself decides whether the next one may proceed.
+ */
+export declare function canLoad(state: PlacementState): boolean;
+/** Only a ready ad may be shown. Everything else is a determinate refusal (FR-028). */
+export declare function canShow(state: PlacementState): boolean;
+export declare function placementReducer(state: PlacementSnapshot, event: PlacementEvent, format: AdFormat): PlacementSnapshot;
+//# sourceMappingURL=placementMachine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"placementMachine.d.ts","sourceRoot":"","sources":["../../../../src/core/placementMachine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,oBAAiB,CAAC;AACnF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAAuB,CAAC;AAEtD,MAAM,MAAM,cAAc,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAE9B,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,eAAO,MAAM,gBAAgB,EAAE,iBAK9B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAQtD;AAED,uFAAuF;AACvF,wBAAgB,OAAO,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAEtD;AAED,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,iBAAiB,EACxB,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,QAAQ,GACd,iBAAiB,CAyDnB"}

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

@@ -0,0 +1,40 @@
+/**
+ * The privacy gate (FR-016 – FR-021).
+ *
+ * The package enforces ordering; the app owns policy. It renders no consent UI,
+ * writes no legal copy, and decides nothing about a jurisdiction — it accepts a
+ * gate outcome and refuses to let any request precede it.
+ *
+ * That refusal is the whole value. Consent ordering is easy to get wrong by
+ * accident, and the failure is invisible: an ad request that should not have
+ * happened looks exactly like one that should. A package that enforces the order
+ * is worth more than documentation that describes it.
+ *
+ * Pure — no provider, no React, no I/O. The engine adapter translates the
+ * outcome into provider configuration.
+ */
+import type { PrivacyBlockReason, PrivacyOptions } from '../config/types.js';
+import type { EnginePrivacy, EngineRequestOptions } from '../engine/port.js';
+export type GateDecision = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly reason: PrivacyBlockReason;
+};
+export declare function evaluateGate(privacy: PrivacyOptions | null): GateDecision;
+export declare function requiresReinitialization(applied: PrivacyOptions | null, next: PrivacyOptions): boolean;
+/**
+ * Projects consumer privacy options onto what the engine needs.
+ *
+ * `personalizedAds` is carried through rather than inverted here; the adapter
+ * owns the translation to the provider's `requestNonPersonalizedAdsOnly`, so
+ * the polarity flip lives next to the API that requires it.
+ */
+export declare function toEnginePrivacy(privacy: PrivacyOptions, testDeviceIds: readonly string[]): EnginePrivacy;
+/**
+ * What every ad request carries. Unset means personalized, matching the
+ * documented default of `PrivacyOptions.personalizedAds`; only an explicit
+ * `false` opts out.
+ */
+export declare function toEngineRequest(privacy: PrivacyOptions | null): EngineRequestOptions;
+//# sourceMappingURL=privacyGate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"privacyGate.d.ts","sourceRoot":"","sources":["../../../../src/core/privacyGate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,oBAAiB,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,mBAAgB,CAAC;AAE1E,MAAM,MAAM,YAAY,GACvB;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAE/F,wBAAgB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,YAAY,CAczE;AAmBD,wBAAgB,wBAAwB,CACvC,OAAO,EAAE,cAAc,GAAG,IAAI,EAC9B,IAAI,EAAE,cAAc,GAClB,OAAO,CAKT;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,cAAc,EACvB,aAAa,EAAE,SAAS,MAAM,EAAE,GAC9B,aAAa,CAQf;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,oBAAoB,CAEpF"}

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

@@ -0,0 +1,99 @@
+/**
+ * Per-placement request throttle (FR-140).
+ *
+ * This exists to protect the **ad account**, not to shape product behaviour, and
+ * that distinction is the whole reason it lives in the package:
+ *
+ * | Decision | Owner |
+ * |---|---|
+ * | How often to *show* an interstitial | the app — product policy |
+ * | How often the same placement may *request* | the package — account safety |
+ *
+ * Rapid repeat requests for one placement are read by ad networks as invalid
+ * traffic, and the penalty is account-level and not recoverable by shipping a
+ * fix. That puts it in the same class as the test-ad substitution the package
+ * already enforces: a safety property the library guarantees rather than
+ * documents and hopes each app remembers.
+ *
+ * ## The pattern it is built for
+ *
+ * A banner mounted inside a view the user navigates between — a day in a
+ * calendar, a tab, a row in a list — is unmounted and remounted by React on every
+ * navigation. Each remount is a fresh provider request. A user swiping quickly
+ * through ten days produces ten requests in a few seconds, and nothing about that
+ * is the app author doing something wrong.
+ *
+ * Full-screen formats do not have this problem: they are loaded by an explicit
+ * call, not mounted by a renderer. That asymmetry is why the default differs by
+ * format — see `defaultMinRequestIntervalMs`.
+ *
+ * The better *architectural* answer is to keep the banner outside the subtree that
+ * remounts. This throttle is the safety net for when that is not possible, not a
+ * licence to ignore the problem; the README says so where an app author will read
+ * it.
+ */
+import type { AdFormat } from '../config/types.js';
+/**
+ * AdMob's own documented floor for banner auto-refresh is 60 seconds, so
+ * requesting the same banner placement more often than that is, by the provider's
+ * own standard, more often than it considers reasonable. Taking the provider's
+ * number rather than inventing one means the default is defensible rather than
+ * arbitrary.
+ */
+export declare const DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS = 60000;
+/**
+ * Off by default for full-screen formats.
+ *
+ * `load` → `show` → `load` is the normal, healthy cycle for an interstitial, and
+ * an app that sells three things in two minutes legitimately loads three times.
+ * Throttling that by default would break correct apps to solve a problem those
+ * formats do not have. An app that wants a floor here can set one.
+ */
+export declare const DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS = 0;
+export declare const MIN_REQUEST_INTERVAL_BOUNDS: {
+    readonly min: 0;
+    readonly max: 600000;
+};
+/** The format-aware default, applied when a placement configures nothing. */
+export declare function defaultMinRequestIntervalMs(format: AdFormat): number;
+export type ThrottleDecision = {
+    readonly allowed: true;
+}
+/**
+ * `retryAfterMs` is reported rather than left for the caller to compute,
+ * because the app needs it to decide between collapsing the space and holding
+ * it — and a caller recomputing it from a timestamp would drift from the
+ * clock this throttle actually used.
+ */
+ | {
+    readonly allowed: false;
+    readonly retryAfterMs: number;
+};
+export interface RequestThrottle {
+    /**
+     * Records a request and reports whether it may proceed.
+     *
+     * Call immediately before handing a request to the provider.
+     *
+     * `token` makes the acquisition **idempotent for one request cycle**, and the
+     * banner path depends on it. React may run a `useMemo` or an effect more than
+     * once for a single committed render — StrictMode does it deliberately — and
+     * without a token the second run would consume a second slot and be refused,
+     * so a banner would never appear in development. Passing the banner mount's
+     * token means "this is the same request I already asked about", and the
+     * previous decision is returned unchanged.
+     *
+     * Omit `token` for a genuinely new imperative request, where every call is a
+     * distinct intent to ask the network.
+     */
+    tryAcquire(key: string, minIntervalMs: number, token?: string): ThrottleDecision;
+    /**
+     * How long until this placement may ask again, without taking a slot: 0 when
+     * it may ask now. A load retry waits at least this long, so a retry policy
+     * cannot request faster than the floor allows (ADS-07).
+     */
+    waitFor(key: string, minIntervalMs: number): number;
+    clear(): void;
+}
+export declare function createRequestThrottle(now: () => number): RequestThrottle;
+//# sourceMappingURL=requestThrottle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"requestThrottle.d.ts","sourceRoot":"","sources":["../../../../src/core/requestThrottle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAiB,CAAC;AAEhD;;;;;;GAMG;AACH,eAAO,MAAM,sCAAsC,QAAS,CAAC;AAE7D;;;;;;;GAOG;AACH,eAAO,MAAM,2CAA2C,IAAI,CAAC;AAE7D,eAAO,MAAM,2BAA2B;;;CAAoC,CAAC;AAE7E,6EAA6E;AAC7E,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,CAIpE;AAED,MAAM,MAAM,gBAAgB,GACzB;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE;AAC5B;;;;;GAKG;GACD;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9D,MAAM,WAAW,eAAe;IAC/B;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACjF;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;IACpD,KAAK,IAAI,IAAI,CAAC;CACd;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,MAAM,GAAG,eAAe,CAmExE"}

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

@@ -0,0 +1,66 @@
+/**
+ * Bounded, opt-in retry for failed loads (FR-134 – FR-139).
+ *
+ * 0.1.0 shipped no retry on purpose, and the reason was sound: every retry is a
+ * billable request, and only the app knows what that costs. But the practical
+ * result was that every app rewrote the same backoff loop, and the cost of
+ * writing it wrong landed on a bill. This ships the loop once, keeps it **off by
+ * default**, and makes every attempt visible.
+ *
+ * Three properties do the work:
+ *
+ *   - Off unless configured, so upgrading from 0.1.0 issues not one extra
+ *     request (FR-134, and the compat test proves it rather than asserting it).
+ *   - Only `retryable` errors. Configuration and consent errors, an unsupported
+ *     platform, and a disabled or undecided instance are states another attempt
+ *     cannot change, so retrying them would spend money on a certainty (FR-135).
+ *   - Every attempt is an event carrying the load cycle's correlation id, so a
+ *     bill can be reconciled against the event stream alone (FR-138).
+ *
+ * Pure — the schedule is computed here, the waiting happens in the instance's
+ * TimerSet so `dispose()` can prove it released everything.
+ */
+import type { RetryPolicy } from '../config/types.js';
+export interface ResolvedRetryPolicy {
+    readonly maxRetries: number;
+    readonly initialDelayMs: number;
+    readonly maxDelayMs: number;
+}
+/**
+ * Validates one policy against the bounds.
+ *
+ * Out-of-range values **throw** rather than being clamped, matching the rule
+ * `timers.ts` already follows: silently clamping a request for ten retries down
+ * to five tells the app it configured something it did not, and the discrepancy
+ * only surfaces later as a bill that does not match the code.
+ *
+ * `label` names the offending field precisely — an error that says only
+ * "invalid retry policy" makes an integrator hunt through a catalog by hand.
+ */
+export declare function resolveRetryPolicy(policy: RetryPolicy, label: string): ResolvedRetryPolicy;
+/**
+ * Resolves the effective policy for one placement.
+ *
+ * An override **replaces** the instance-wide policy rather than merging into it.
+ * Merging would mean the effective policy for a placement could not be read off
+ * the configuration — you would have to simulate the merge to know what it was —
+ * and a per-field merge makes "this placement retries twice" quietly depend on a
+ * value written somewhere else.
+ *
+ * Both are validated against the same bounds, so an override narrows behavior
+ * but can never exceed a ceiling (FR-136a).
+ */
+export declare function resolveEffectiveRetry(instancePolicy: RetryPolicy | undefined, placementPolicy: RetryPolicy | false | undefined, placementKey: string): ResolvedRetryPolicy | null;
+/**
+ * Delay before the given attempt. `attempt` is 1-based — the first retry is 1.
+ *
+ * Exponential with a fixed x2 multiplier and **no jitter**. Jitter exists to
+ * desynchronize a fleet of clients hitting one server; a single device retrying
+ * its own load has no herd to avoid. Leaving it out keeps "two retries, 2s then
+ * 4s" an exact assertion instead of a statistical one, which matters more here
+ * than a property that does not apply.
+ */
+export declare function delayForAttempt(policy: ResolvedRetryPolicy, attempt: number): number;
+/** Whether another attempt is permitted. `attemptsMade` counts retries only. */
+export declare function canRetry(policy: ResolvedRetryPolicy | null, attemptsMade: number): boolean;
+//# sourceMappingURL=retryPolicy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retryPolicy.d.ts","sourceRoot":"","sources":["../../../../src/core/retryPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAMH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAiB,CAAC;AAEnD,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,mBAAmB,CAiC1F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACpC,cAAc,EAAE,WAAW,GAAG,SAAS,EACvC,eAAe,EAAE,WAAW,GAAG,KAAK,GAAG,SAAS,EAChD,YAAY,EAAE,MAAM,GAClB,mBAAmB,GAAG,IAAI,CAgB5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAOpF;AAED,gFAAgF;AAChF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAE1F"}

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

@@ -0,0 +1,37 @@
+/**
+ * Rewarded session bookkeeping (FR-046 – FR-049).
+ *
+ * Two independent booleans, never derived from one another:
+ *
+ *              rewardConfirmed=false        rewardConfirmed=true
+ *   dismissed=false   in progress           reward emitted, awaiting dismissal
+ *   dismissed=true    dismissed_no_reward   earned
+ *
+ * The defect this exists to prevent is inferring "earned" from dismissal. It is
+ * the most common way rewarded integrations go wrong, and it is a direct revenue
+ * and fairness fault: a user who closed the ad after two seconds gets the prize,
+ * and the publisher is billed for nothing.
+ *
+ * Tracking two flags and deriving the outcome makes both callback orderings
+ * produce the same result *by construction* rather than by the provider
+ * happening to fire in a convenient order (SC-007).
+ */
+import type { Reward } from '../config/types.js';
+export type RewardedOutcome = 'in_progress' | 'earned' | 'dismissed_without_reward';
+export interface RewardedSession {
+    /**
+     * Records a provider reward confirmation. Returns the reward the first time
+     * and `null` on every repeat, which is what collapses a duplicate provider
+     * emission into exactly one public event (FR-054).
+     */
+    confirmReward(reward: Reward): Reward | null;
+    /** Records dismissal. Returns true the first time only. */
+    dismiss(): boolean;
+    outcome(): RewardedOutcome;
+    /** True only once the provider actually confirmed. Never inferred (FR-046). */
+    get rewardEarned(): boolean;
+    get dismissed(): boolean;
+    reward(): Reward | null;
+}
+export declare function createRewardedSession(): RewardedSession;
+//# sourceMappingURL=rewardedSession.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rewardedSession.d.ts","sourceRoot":"","sources":["../../../../src/core/rewardedSession.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAiB,CAAC;AAE9C,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,QAAQ,GAAG,0BAA0B,CAAC;AAEpF,MAAM,WAAW,eAAe;IAC/B;;;;OAIG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC7C,2DAA2D;IAC3D,OAAO,IAAI,OAAO,CAAC;IACnB,OAAO,IAAI,eAAe,CAAC;IAC3B,+EAA+E;IAC/E,IAAI,YAAY,IAAI,OAAO,CAAC;IAC5B,IAAI,SAAS,IAAI,OAAO,CAAC;IACzB,MAAM,IAAI,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,wBAAgB,qBAAqB,IAAI,eAAe,CA4CvD"}