@revturbine/sdk 0.2.57 → 0.2.59

package/dist/headless.d.ts

@@ -1739,6 +1739,7 @@ declare const PlacementPayloadSchema: z.ZodObject<{
         session: "session";
     }>>;
     cooldown_after_dismiss_days: z.ZodDefault<z.ZodNumber>;
+    remind_later_minutes: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
     recommendation_strategy: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
         custom: "custom";
         next_tier_up: "next_tier_up";
@@ -3714,6 +3715,7 @@ declare const PlacementSettingsCapStateSchema: z.ZodObject<{
         }, z.core.$strip>;
     }, z.core.$strip>>>;
     sessionCooldownMinutes: z.ZodDefault<z.ZodNumber>;
+    remindLaterMinutes: z.ZodDefault<z.ZodNumber>;
     testMode: z.ZodDefault<z.ZodEnum<{
         off: "off";
         test_users: "test_users";
@@ -3756,6 +3758,7 @@ declare const PlacementSettingsSchema: z.ZodObject<{
             }, z.core.$strip>;
         }, z.core.$strip>>>;
         sessionCooldownMinutes: z.ZodDefault<z.ZodNumber>;
+        remindLaterMinutes: z.ZodDefault<z.ZodNumber>;
         testMode: z.ZodDefault<z.ZodEnum<{
             off: "off";
             test_users: "test_users";
@@ -3771,7 +3774,6 @@ declare const PlacementSettingsSchema: z.ZodObject<{
     }>>>;
     suppress_for_paid: z.ZodDefault<z.ZodBoolean>;
     suppress_for_trial: z.ZodDefault<z.ZodBoolean>;
-    default_dismiss_cooldown_hours: z.ZodDefault<z.ZodNumber>;
     allow_stacking: z.ZodDefault<z.ZodBoolean>;
     priority_collision_strategy: z.ZodDefault<z.ZodEnum<{
         highest_priority: "highest_priority";
@@ -3941,6 +3943,7 @@ declare const RevTurbineConfigPlacementSettingsItemSchema: z.ZodObject<{
             }, z.core.$strip>;
         }, z.core.$strip>>>;
         sessionCooldownMinutes: z.ZodDefault<z.ZodNumber>;
+        remindLaterMinutes: z.ZodDefault<z.ZodNumber>;
         testMode: z.ZodDefault<z.ZodEnum<{
             off: "off";
             test_users: "test_users";
@@ -3956,7 +3959,6 @@ declare const RevTurbineConfigPlacementSettingsItemSchema: z.ZodObject<{
     }>>>;
     suppress_for_paid: z.ZodDefault<z.ZodBoolean>;
     suppress_for_trial: z.ZodDefault<z.ZodBoolean>;
-    default_dismiss_cooldown_hours: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
     allow_stacking: z.ZodDefault<z.ZodBoolean>;
     priority_collision_strategy: z.ZodDefault<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
@@ -4346,6 +4348,7 @@ declare const RevTurbineConfigStudioPayloadSchema: z.ZodObject<{
         cooldown_days: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
     surface_slot_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    remind_later_minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     created_at: z.ZodOptional<z.ZodString>;
     recommendation_strategy: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
         custom: "custom";
@@ -4499,6 +4502,7 @@ declare const RevTurbineConfigPlacementItemSchema: z.ZodObject<{
             cooldown_days: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
         surface_slot_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        remind_later_minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         created_at: z.ZodOptional<z.ZodString>;
         recommendation_strategy: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
             custom: "custom";
@@ -4530,6 +4534,7 @@ declare const RevTurbineConfigPlacementPayloadItemSchema: z.ZodObject<{
         }, z.core.$strip>>;
         cooldown_days: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
+    remind_later_minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     created_at: z.ZodString;
     updated_at: z.ZodOptional<z.ZodString>;
     source_mode: z.ZodEnum<{
@@ -4809,6 +4814,7 @@ declare const PlaybookBodySchema: z.ZodObject<{
             }, z.core.$strip>>;
             cooldown_days: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
+        remind_later_minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         created_at: z.ZodString;
         updated_at: z.ZodOptional<z.ZodString>;
         source_mode: z.ZodEnum<{
@@ -4948,6 +4954,7 @@ declare const PlaybookBodySchema: z.ZodObject<{
                 cooldown_days: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
             surface_slot_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            remind_later_minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
             created_at: z.ZodOptional<z.ZodString>;
             recommendation_strategy: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
                 custom: "custom";
@@ -5147,6 +5154,7 @@ declare const PlaybookBodySchema: z.ZodObject<{
                 }, z.core.$strip>;
             }, z.core.$strip>>>;
             sessionCooldownMinutes: z.ZodDefault<z.ZodNumber>;
+            remindLaterMinutes: z.ZodDefault<z.ZodNumber>;
             testMode: z.ZodDefault<z.ZodEnum<{
                 off: "off";
                 test_users: "test_users";
@@ -5162,7 +5170,6 @@ declare const PlaybookBodySchema: z.ZodObject<{
         }>>>;
         suppress_for_paid: z.ZodDefault<z.ZodBoolean>;
         suppress_for_trial: z.ZodDefault<z.ZodBoolean>;
-        default_dismiss_cooldown_hours: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
         allow_stacking: z.ZodDefault<z.ZodBoolean>;
         priority_collision_strategy: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>>;
@@ -5453,6 +5460,7 @@ declare const PlaybookObjectSchema: z.ZodObject<{
             }, z.core.$strip>>;
             cooldown_days: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
+        remind_later_minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         created_at: z.ZodString;
         updated_at: z.ZodOptional<z.ZodString>;
         source_mode: z.ZodEnum<{
@@ -5592,6 +5600,7 @@ declare const PlaybookObjectSchema: z.ZodObject<{
                 cooldown_days: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
             surface_slot_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            remind_later_minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
             created_at: z.ZodOptional<z.ZodString>;
             recommendation_strategy: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
                 custom: "custom";
@@ -5791,6 +5800,7 @@ declare const PlaybookObjectSchema: z.ZodObject<{
                 }, z.core.$strip>;
             }, z.core.$strip>>>;
             sessionCooldownMinutes: z.ZodDefault<z.ZodNumber>;
+            remindLaterMinutes: z.ZodDefault<z.ZodNumber>;
             testMode: z.ZodDefault<z.ZodEnum<{
                 off: "off";
                 test_users: "test_users";
@@ -5806,7 +5816,6 @@ declare const PlaybookObjectSchema: z.ZodObject<{
         }>>>;
         suppress_for_paid: z.ZodDefault<z.ZodBoolean>;
         suppress_for_trial: z.ZodDefault<z.ZodBoolean>;
-        default_dismiss_cooldown_hours: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
         allow_stacking: z.ZodDefault<z.ZodBoolean>;
         priority_collision_strategy: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>>;
@@ -6084,6 +6093,7 @@ declare const PlaybookSchema: z.ZodPreprocess<z.ZodObject<{
             }, z.core.$strip>>;
             cooldown_days: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
+        remind_later_minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         created_at: z.ZodString;
         updated_at: z.ZodOptional<z.ZodString>;
         source_mode: z.ZodEnum<{
@@ -6223,6 +6233,7 @@ declare const PlaybookSchema: z.ZodPreprocess<z.ZodObject<{
                 cooldown_days: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
             surface_slot_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            remind_later_minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
             created_at: z.ZodOptional<z.ZodString>;
             recommendation_strategy: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
                 custom: "custom";
@@ -6422,6 +6433,7 @@ declare const PlaybookSchema: z.ZodPreprocess<z.ZodObject<{
                 }, z.core.$strip>;
             }, z.core.$strip>>>;
             sessionCooldownMinutes: z.ZodDefault<z.ZodNumber>;
+            remindLaterMinutes: z.ZodDefault<z.ZodNumber>;
             testMode: z.ZodDefault<z.ZodEnum<{
                 off: "off";
                 test_users: "test_users";
@@ -6437,7 +6449,6 @@ declare const PlaybookSchema: z.ZodPreprocess<z.ZodObject<{
         }>>>;
         suppress_for_paid: z.ZodDefault<z.ZodBoolean>;
         suppress_for_trial: z.ZodDefault<z.ZodBoolean>;
-        default_dismiss_cooldown_hours: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
         allow_stacking: z.ZodDefault<z.ZodBoolean>;
         priority_collision_strategy: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>>;
@@ -6733,6 +6744,7 @@ declare const PlaybookStrictSchema: z.ZodPreprocess<z.ZodObject<{
             }, z.core.$strip>>;
             cooldown_days: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
+        remind_later_minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         created_at: z.ZodString;
         updated_at: z.ZodOptional<z.ZodString>;
         source_mode: z.ZodEnum<{
@@ -6872,6 +6884,7 @@ declare const PlaybookStrictSchema: z.ZodPreprocess<z.ZodObject<{
                 cooldown_days: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
             surface_slot_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            remind_later_minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
             created_at: z.ZodOptional<z.ZodString>;
             recommendation_strategy: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
                 custom: "custom";
@@ -7071,6 +7084,7 @@ declare const PlaybookStrictSchema: z.ZodPreprocess<z.ZodObject<{
                 }, z.core.$strip>;
             }, z.core.$strip>>>;
             sessionCooldownMinutes: z.ZodDefault<z.ZodNumber>;
+            remindLaterMinutes: z.ZodDefault<z.ZodNumber>;
             testMode: z.ZodDefault<z.ZodEnum<{
                 off: "off";
                 test_users: "test_users";
@@ -7086,7 +7100,6 @@ declare const PlaybookStrictSchema: z.ZodPreprocess<z.ZodObject<{
         }>>>;
         suppress_for_paid: z.ZodDefault<z.ZodBoolean>;
         suppress_for_trial: z.ZodDefault<z.ZodBoolean>;
-        default_dismiss_cooldown_hours: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
         allow_stacking: z.ZodDefault<z.ZodBoolean>;
         priority_collision_strategy: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>>;
@@ -7361,6 +7374,7 @@ declare const RevTurbineConfigSchema: z.ZodPreprocess<z.ZodObject<{
             }, z.core.$strip>>;
             cooldown_days: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
+        remind_later_minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         created_at: z.ZodString;
         updated_at: z.ZodOptional<z.ZodString>;
         source_mode: z.ZodEnum<{
@@ -7500,6 +7514,7 @@ declare const RevTurbineConfigSchema: z.ZodPreprocess<z.ZodObject<{
                 cooldown_days: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
             surface_slot_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            remind_later_minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
             created_at: z.ZodOptional<z.ZodString>;
             recommendation_strategy: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
                 custom: "custom";
@@ -7699,6 +7714,7 @@ declare const RevTurbineConfigSchema: z.ZodPreprocess<z.ZodObject<{
                 }, z.core.$strip>;
             }, z.core.$strip>>>;
             sessionCooldownMinutes: z.ZodDefault<z.ZodNumber>;
+            remindLaterMinutes: z.ZodDefault<z.ZodNumber>;
             testMode: z.ZodDefault<z.ZodEnum<{
                 off: "off";
                 test_users: "test_users";
@@ -7714,7 +7730,6 @@ declare const RevTurbineConfigSchema: z.ZodPreprocess<z.ZodObject<{
         }>>>;
         suppress_for_paid: z.ZodDefault<z.ZodBoolean>;
         suppress_for_trial: z.ZodDefault<z.ZodBoolean>;
-        default_dismiss_cooldown_hours: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
         allow_stacking: z.ZodDefault<z.ZodBoolean>;
         priority_collision_strategy: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>>;
@@ -9866,7 +9881,7 @@ interface InteractionTrackerOptions {
     storage: RevTurbineStorage;
     tenantId: string;
     userId: string;
-    /** Default dismiss cooldown (ms). Default: 24 hours. */
+    /** Default dismiss cooldown (ms). Default: 7 days (`cooldown_after_dismiss_days`). */
     defaultDismissCooldownMs?: number;
     /** Default remind-me-later delay (ms). Default: 1 hour. */
     defaultRemindLaterMs?: number;
@@ -10029,19 +10044,29 @@ declare class DecisionEngine {
 /**
  * Impression history types.
  *
- * Tracks placement impressions and terminal interactions (dismiss, click-through,
- * suppress) so the decision engine can permanently exclude placements the user
- * has already acted on.
+ * 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.
  */
 /**
  * Interaction outcomes tracked by the impression history system.
  *
- * - `'impressed'`    — the placement was shown to the user.
- * - `'dismissed'`    — user explicitly closed the placement (permanent).
- * - `'clicked_thru'` — user clicked the CTA (permanent).
- * - `'suppressed'`   — system or admin suppressed the placement (time-based).
+ * - `'impressed'`     — the placement was shown to the user.
+ * - `'dismissed'`     — user explicitly closed the placement ("No thanks").
+ *   Time-boxed: the placement re-shows after the dismiss cooldown
+ *   (`cooldown_after_dismiss_days`, default 7d). Spec: placement-studio-ui.md §
+ *   "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.
+ * - `'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.
  */
-type ImpressionOutcome = 'impressed' | 'dismissed' | 'clicked_thru' | 'suppressed';
+type ImpressionOutcome = 'impressed' | 'dismissed' | 'clicked_thru' | 'cta_completed' | 'suppressed';
 /**
  * A single impression/interaction history record.
  */
@@ -10086,14 +10111,16 @@ interface ImpressionHistoryStore {
     query(userId: string, query?: ImpressionQuery): ImpressionRecord[] | Promise<ImpressionRecord[]>;
     /**
      * Return the set of placement IDs that have a terminal outcome
-     * for this user (dismissed / clicked_thru).
+     * for this user (`cta_completed` — a confirmed conversion).
      *
      * This is the hot-path check used by the resolver.
      */
     getRetiredPlacementIds(userId: string): Set<string> | Promise<Set<string>>;
     /**
      * Return a map of placement IDs → `suppressUntil` ISO timestamps
-     * for placements with active suppression windows.
+     * for placements with an active cooldown window — i.e. any record
+     * (`dismissed`, `clicked_thru`, or `suppressed`) carrying a future
+     * `suppressUntil`.
      */
     getSuppressedPlacements(userId: string): Map<string, string> | Promise<Map<string, string>>;
     /** Remove all records for a user. */
@@ -10118,17 +10145,25 @@ interface ImpressionHistoryOptions {
     userId: string;
     /** Default suppression duration in milliseconds. Default: 24 h. */
     defaultSuppressionMs?: number;
+    /**
+     * Default dismiss cooldown in milliseconds — applied to `dismissed` and bare
+     * `clicked_thru` outcomes when no explicit window is supplied. Default: 7 days
+     * (mirrors `cooldown_after_dismiss_days`).
+     */
+    defaultDismissCooldownMs?: number;
 }
 declare class ImpressionHistory {
     private readonly store;
     private userId;
     private readonly defaultSuppressionMs;
+    private readonly defaultDismissCooldownMs;
     /**
-     * Hot cache of permanently retired placement IDs (dismissed / clicked_thru).
+     * 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;
     constructor(options: ImpressionHistoryOptions);
@@ -10137,15 +10172,30 @@ declare class ImpressionHistory {
      */
     recordImpression(placementId: string, payloadId?: string, surfaceTemplateId?: string, metadata?: Record<string, unknown>): Promise<void>;
     /**
-     * Record a dismissal — the user explicitly closed the placement.
-     * The placement is permanently retired for this user.
+     * Record a dismissal — the user explicitly closed the placement ("No thanks").
+     * Time-boxed: the placement is hidden for a cooldown window and re-shows once
+     * it elapses (plan 167, Q-1; spec placement-studio-ui.md:311). NOT permanent.
+     *
+     * @param cooldownMs — cooldown window in ms. Falls back to
+     *   `defaultDismissCooldownMs` (7 days). The SDK resolves this from the
+     *   placement's `cooldown_after_dismiss_days`.
      */
-    recordDismissal(placementId: string, payloadId?: string, surfaceTemplateId?: string, metadata?: Record<string, unknown>): Promise<void>;
+    recordDismissal(placementId: string, payloadId?: string, surfaceTemplateId?: string, metadata?: Record<string, unknown>, cooldownMs?: number): Promise<void>;
     /**
-     * Record a click-through — the user engaged with the CTA.
-     * The placement is permanently retired for this user.
+     * Record a bare click-through — the user clicked the CTA but did **not**
+     * confirm the conversion (e.g. abandoned checkout). Treated as a cooldown,
+     * identical to a dismiss — they may return (plan 167, Q-1). For a confirmed
+     * conversion use {@link recordConversion} instead.
+     *
+     * @param cooldownMs — cooldown window in ms. Falls back to
+     *   `defaultDismissCooldownMs` (7 days).
      */
-    recordClickThru(placementId: string, payloadId?: string, surfaceTemplateId?: string, metadata?: Record<string, unknown>): Promise<void>;
+    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).
+     */
+    recordConversion(placementId: string, payloadId?: string, surfaceTemplateId?: string, metadata?: Record<string, unknown>): Promise<void>;
     /**
      * Record a suppression — the system or admin suppressed the placement.
      * The placement is hidden for a configurable duration (not permanent).
@@ -11081,6 +11131,15 @@ interface PlacementSlotProps<C extends ResolvedContent = ResolvedContent> {
     onSecondaryCtaClick?: () => void;
     /** Callback when user dismisses the placement. */
     onDismiss: () => void;
+    /**
+     * Optional callback when the user chooses "Remind me later" (defer). When
+     * provided, dismissible slots render a defer control beside dismiss; the
+     * placement re-queues and reappears after the remind-later window
+     * (`remind_later_minutes`, default 60) rather than the longer dismiss
+     * cooldown (plan 167 REQ-7). **Additive and optional** — omit it and slots
+     * render exactly as before, with no defer control.
+     */
+    onRemindLater?: () => void;
     /** Whether the placement is currently visible. */
     visible: boolean;
     /** Custom CSS class name for styling overrides. */
@@ -12379,6 +12438,13 @@ declare class RevTurbineCustomerSdk {
     private readonly interactionQueue;
     private readonly defaultDecisionTtlMs;
     private readonly defaultDismissCooldownMs;
+    /**
+     * Default dismiss cooldown window — 7 days, matching the engine's
+     * `cooldown_after_dismiss_days` default. Applied to `dismiss` and bare
+     * `cta_clicked` when the payload supplies no explicit `cooldown_ms`
+     * (plan 167 REQ-3 / Q-1). Replaces the legacy 24h dismiss window.
+     */
+    private readonly dismissCooldownDefaultMs;
     private readonly defaultRemindLaterMs;
     private readonly defaultUsageWarningPercent;
     private readonly defaultTrialExpiringDays;
@@ -12872,26 +12938,43 @@ declare class RevTurbineCustomerSdk {
      */
     recordImpression(placementId: string, payloadId?: string, surfaceTemplateId?: string, metadata?: RevTurbineImpressionMetadata): Promise<void>;
     /**
-     * Record a placement dismissal — the user explicitly closed it.
-     * The placement is permanently retired for this user; subsequent
-     * `getPlacementDecision` calls return `visible: false`.
+     * Record a placement dismissal — the user explicitly closed it ("No thanks").
+     * Time-boxed: the placement is hidden for the dismiss cooldown
+     * (`cooldown_after_dismiss_days`, default 7 days) and re-shows once it elapses
+     * (plan 167). NOT permanent — for a confirmed conversion use
+     * {@link recordConversion}.
+     *
+     * @param placementId - The placement's stable rule_id.
+     * @param payloadId - Optional payload variant id.
+     * @param surfaceTemplateId - Optional surface template id.
+     * @param metadata - Optional metadata persisted with the record.
+     * @param cooldownMs - Optional explicit cooldown window (ms). Defaults to 7 days.
+     */
+    recordDismissal(placementId: string, payloadId?: string, surfaceTemplateId?: string, metadata?: RevTurbineImpressionMetadata, cooldownMs?: number): Promise<void>;
+    /**
+     * Record a bare placement click-through — the user clicked the CTA but did
+     * not confirm the conversion (e.g. abandoned checkout). Time-boxed like a
+     * dismiss; the placement may return (plan 167). For a confirmed conversion
+     * use {@link recordConversion}.
      *
      * @param placementId - The placement's stable rule_id.
      * @param payloadId - Optional payload variant id.
      * @param surfaceTemplateId - Optional surface template id.
      * @param metadata - Optional metadata persisted with the record.
+     * @param cooldownMs - Optional explicit cooldown window (ms). Defaults to 7 days.
      */
-    recordDismissal(placementId: string, payloadId?: string, surfaceTemplateId?: string, metadata?: RevTurbineImpressionMetadata): Promise<void>;
+    recordClickThru(placementId: string, payloadId?: string, surfaceTemplateId?: string, metadata?: RevTurbineImpressionMetadata, cooldownMs?: number): Promise<void>;
     /**
-     * Record a placement click-through — the user engaged with the CTA.
-     * The placement is permanently retired for this user.
+     * 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).
      *
      * @param placementId - The placement's stable rule_id.
      * @param payloadId - Optional payload variant id.
      * @param surfaceTemplateId - Optional surface template id.
      * @param metadata - Optional metadata persisted with the record.
      */
-    recordClickThru(placementId: string, payloadId?: string, surfaceTemplateId?: string, metadata?: RevTurbineImpressionMetadata): Promise<void>;
+    recordConversion(placementId: string, payloadId?: string, surfaceTemplateId?: string, metadata?: RevTurbineImpressionMetadata): Promise<void>;
     getTrialStatus(): Promise<RevTurbineTrialContext>;
     /**
      * Derive and push the user's trial status from their {@link TrialInstance}