@revturbine/sdk 0.8.9 → 0.9.1

package/dist/headless.d.ts

@@ -16536,6 +16536,8 @@ interface RevTurbineTreatmentInteractionInput {
 interface InteractionState {
     /** Unix timestamp (ms) — when suppression expires. */
     suppressedUntil?: number;
+    /** Independent system suppression expiry; category exemptions never bypass it. */
+    explicitSuppressedUntil?: number;
     /** Type of last interaction. */
     lastInteractionType?: RevTurbineTreatmentInteractionType;
     /** ISO timestamp of last update. */
@@ -17170,7 +17172,7 @@ declare class InteractionTracker {
     /** Track an interaction and update suppression state. */
     track(input: RevTurbineTreatmentInteractionInput): void;
     /** Check whether a placement is suppressed by a recent interaction. */
-    checkSuppression(placementId: string, userId: string, treatmentId?: string): SuppressionResult;
+    checkSuppression(placementId: string, userId: string, treatmentId?: string, category?: string): SuppressionResult;
     /** Clear suppression state for a specific placement. */
     clearSuppression(placementId: string, userId: string, treatmentId?: string): void;
     /** Load state from storage. Called automatically on construction. */
@@ -17252,11 +17254,11 @@ interface EvaluationContext {
  * DecisionEngine — isomorphic placement decision pipeline.
  *
  * Runs the full decision flow:
- *   1. Check dismissal suppression (InteractionTracker)
- *   2. Resolve domain providers (DomainProviderRegistry)
- *   3. Evaluate segments
- *   4. Match entitlement rules
- *   5. Resolve placement (local resolver or pre-resolved output)
+ *   1. Resolve domain providers (DomainProviderRegistry)
+ *   2. Evaluate segments
+ *   3. Match entitlement rules
+ *   4. Resolve placement (local resolver or pre-resolved output)
+ *   5. Apply category-aware interaction suppression (InteractionTracker)
  *   6. Enforce presentation caps (CapEnforcer)
  *   7. Return decision
  *
@@ -17288,8 +17290,8 @@ declare class DecisionEngine {
     /**
      * Evaluate a single placement decision.
      *
-     * Full pipeline: suppression check → provider resolution → segment evaluation →
-     * local resolver → cap enforcement → decision.
+     * Full pipeline: provider resolution → segment evaluation → local resolver →
+     * category-aware suppression → cap enforcement → decision.
      */
     evaluate(input: RevTurbinePlacementDecisionInput): Promise<RevTurbinePlacementDecision>;
     /**
@@ -17318,9 +17320,8 @@ declare class DecisionEngine {
  * Impression history types.
  *
  * Tracks placement impressions and interactions (dismiss, click-through,
- * conversion, suppress) so the decision engine can exclude placements the user
- * has already acted on — permanently for a confirmed conversion, or for a
- * cooldown window for a dismiss / bare click / system suppression.
+ * conversion, suppress) for analytics and dismiss / bare click / system
+ * suppression windows. Conversion does not change placement eligibility.
  */
 /**
  * Interaction outcomes tracked by the impression history system.
@@ -17332,12 +17333,11 @@ declare class DecisionEngine {
  *   "Cooldown After Dismiss". NOT permanent.
  * - `'clicked_thru'`  — user clicked the CTA but did **not** confirm completion
  *   (e.g. abandoned checkout). Time-boxed like a dismiss — they may return.
- * - `'cta_completed'` — user confirmed the conversion action. **Permanent** —
- *   a converted user never sees the upsell again.
+ * - `'cta_completed'` — confirmed conversion analytics. Current targeting
+ *   determines whether the placement remains applicable.
  * - `'suppressed'`    — system or admin suppressed the placement (time-based).
  *
- * See plan 167 (Q-1 ruling): only a confirmed conversion is terminal; a dismiss
- * or a bare click is a cooldown.
+ * Plan 254 supersedes plan 167's conversion retirement policy.
  */
 type ImpressionOutcome = 'impressed' | 'dismissed' | 'clicked_thru' | 'cta_completed' | 'suppressed';
 /**
@@ -17383,10 +17383,8 @@ interface ImpressionHistoryStore {
      */
     query(userId: string, query?: ImpressionQuery): ImpressionRecord[] | Promise<ImpressionRecord[]>;
     /**
-     * Return the set of placement IDs that have a terminal outcome
-     * for this user (`cta_completed` — a confirmed conversion).
-     *
-     * This is the hot-path check used by the resolver.
+     * @deprecated Conversion no longer retires placements. Built-in stores return
+     * an empty set; the resolver does not consult custom retirement indexes.
      */
     getRetiredPlacementIds(userId: string): Set<string> | Promise<Set<string>>;
     /**
@@ -17404,8 +17402,8 @@ interface ImpressionHistoryStore {
  * ImpressionHistory — records and queries placement impression/interaction history.
  *
  * Wraps an ImpressionHistoryStore backend and provides a clean API for:
- * - Recording impressions and terminal interactions.
- * - Checking whether a placement is retired (should never be shown again).
+ * - Recording impressions and interactions, including conversion analytics.
+ * - Checking active dismissal and suppression windows.
  * - Querying full history for debugging / analytics.
  *
  * Isomorphic: works with any store backend (in-memory, localStorage, Postgres).
@@ -17430,15 +17428,13 @@ declare class ImpressionHistory {
     private userId;
     private readonly defaultSuppressionMs;
     private readonly defaultDismissCooldownMs;
-    /**
-     * Hot cache of permanently retired placement IDs (confirmed conversions).
-     */
-    private retiredCache;
     /**
      * Hot cache of time-suppressed placement IDs → suppressUntil ISO timestamp.
      * Covers dismiss / bare-click cooldowns and system suppressions.
      */
     private suppressedCache;
+    /** Derived from existing explicit suppression records; never persisted separately. */
+    private explicitSuppressedCache;
     constructor(options: ImpressionHistoryOptions);
     /**
      * Record an impression — the placement was shown to the user.
@@ -17466,7 +17462,7 @@ declare class ImpressionHistory {
     recordClickThru(placementId: string, payloadId?: string, surfaceTemplateId?: string, metadata?: Record<string, unknown>, cooldownMs?: number): Promise<void>;
     /**
      * Record a confirmed conversion — the user completed the CTA action.
-     * The placement is **permanently** retired for this user (plan 167, Q-1).
+     * Analytics only: current targeting determines future eligibility (plan 254).
      */
     recordConversion(placementId: string, payloadId?: string, surfaceTemplateId?: string, metadata?: Record<string, unknown>): Promise<void>;
     /**
@@ -17477,17 +17473,15 @@ declare class ImpressionHistory {
      */
     recordSuppression(placementId: string, payloadId?: string, surfaceTemplateId?: string, metadata?: Record<string, unknown>, durationMs?: number): Promise<void>;
     /**
-     * Check whether a placement has been permanently retired for this user.
+     * @deprecated Placements are no longer retired by conversion. Always false.
      */
     isRetired(placementId: string): Promise<boolean>;
     /**
-     * Return the set of placement IDs retired for this user.
-     * Caches the result for synchronous access via `isRetiredSync()`.
+     * @deprecated Placements are no longer retired by conversion. Always empty.
      */
     getRetiredIds(): Promise<Set<string>>;
     /**
-     * Synchronous check — only valid after `getRetiredIds()` or a recording call
-     * has populated the cache. Returns `false` if the cache is cold.
+     * @deprecated Placements are no longer retired by conversion. Always false.
      */
     isRetiredSync(placementId: string): boolean;
     /**
@@ -17496,15 +17490,15 @@ declare class ImpressionHistory {
      */
     isSuppressedSync(placementId: string): boolean;
     /**
-     * Synchronous check: placement should not be shown (retired OR suppressed).
+     * Synchronous check: placement is within an active suppression window.
      */
-    isHiddenSync(placementId: string): boolean;
+    isHiddenSync(placementId: string, category?: string): boolean;
     /**
      * Query full history (for debugging, analytics, or inspector panels).
      */
     queryHistory(query?: ImpressionQuery): Promise<ImpressionRecord[]>;
     /**
-     * Pre-warm the retired and suppressed caches from the store.
+     * Pre-warm the suppression cache from the store.
      * Call during SDK initialization for synchronous access.
      */
     hydrate(): Promise<void>;
@@ -17517,7 +17511,6 @@ declare class ImpressionHistory {
      */
     setUserId(userId: string): void;
     private appendRecord;
-    private retireInCache;
     private suppressInCache;
 }
 
@@ -18434,6 +18427,8 @@ interface CtaResolverContext {
     placement: PlacementOutput;
     /** Which CTA fired — the primary button or a secondary action. */
     kind: 'primary' | 'secondary';
+    /** Report snooze through the mounted controller and close this occurrence. */
+    remindLater?: (seconds?: number) => void;
 }
 /**
  * Promotion attached to a placement payload.
@@ -20914,7 +20909,7 @@ declare class RevTurbineCustomerSdk {
     private interactionStateKey;
     private readDecisionCache;
     private writeDecisionCache;
-    private suppressionForState;
+    private gateDecisionByInteraction;
     private placementCapKey;
     private extractPlacementCapPolicies;
     private applyPlacementCapsIfNeeded;
@@ -21187,8 +21182,8 @@ declare class RevTurbineCustomerSdk {
     recordClickThru(placementId: string, payloadId?: string, surfaceTemplateId?: string, metadata?: RevTurbineImpressionMetadata, cooldownMs?: number): Promise<void>;
     /**
      * Record a confirmed conversion — the user completed the CTA action. The
-     * placement is **permanently** retired for this user; subsequent
-     * `getPlacementDecision` calls return `visible: false` for good (plan 167).
+     * record is retained for analytics. Future eligibility is evaluated from
+     * the current UserContext and Playbook.
      *
      * @param placementId - The placement's stable rule_id.
      * @param payloadId - Optional payload variant id.
@@ -21248,22 +21243,7 @@ declare class RevTurbineCustomerSdk {
      * throwOnMissing: true })` remains the strict opt-in.
      */
     private warnOnUiPathResolverCoverageGaps;
-    /**
-     * Route an output-addressed interaction through the one interaction path.
-     *
-     * Plan 233 TASK-14. These three methods each emitted a `placement_interaction`
-     * event and stopped, so none of them wrote any terminal state:
-     * `sdk.dismiss()` did not suppress, and `sdk.convert()` did not retire. Only
-     * the controller path (`trackTreatmentInteraction`) ever did, which is why the
-     * defect was invisible to every React integration test.
-     *
-     * The public API takes an **output** id while every terminal-state write is
-     * keyed by the **placement** id, so the output is resolved through
-     * `outputPlacementIndex`. When it cannot be resolved — an output this SDK
-     * instance never decided, or one evicted from a very long session — we emit
-     * the bare event as before and say so. Silently doing nothing is what shipped;
-     * being loud about the one case we cannot serve is the point.
-     */
+    /** Route output-addressed callbacks through the canonical interaction/analytics path. */
     private trackOutputInteraction;
     dismiss(outputId: string): Promise<void>;
     snooze(outputId: string, seconds?: number): Promise<void>;