feat: add gwpApproved setting for gift-with-purchase conversions (#2)

* feat: add gwpApproved setting for gift-with-purchase conversions

Maps a configured custom event name (or comma-separated list) to a new
gwpApproved Pay+ signal, following the same pattern as the other custom
event settings: the signal posts { source, type: 'gwpApproved', detail:
<event attributes>, trigger } to the embedding plugin.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix: rename setting to gwpApprovedEventName + drop drift-prone README settings tables

- rename the setting key gwpApproved -> gwpApprovedEventName to match the
  <signal>EventName convention of the other custom-event settings (nothing
  has shipped server-side yet, so the rename is free)
- replace the README per-setting tables with a drift-proof description of
  the naming convention; the dashboard fields are self-describing

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: mvedma04005 <mani.vedma@rokt.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

README.md

@@ -10,8 +10,8 @@ The kit loads alongside the mParticle web SDK and receives the events your appli
 | :-- | :-- |
 | `initiated` | the kit initializes (application loaded) |
 | `stepComplete` | a configured funnel-step screen is viewed |
-| `approved` | the configured conversion event or screen |
-| `pending`, `loggedIn`, `accountCreated`, `offerSaved`, `purchaseCompleted`, `formSubmitted`, `pendingSuccess`, `close`, `removeLoadingOverlay` | the matching configured event or screen |
+| `approved` | the configured conversion event |
+| every other Pay+ signal (`pending`, `accountCreated`, `purchaseCompleted`, ...) | the matching configured custom event |
 
 ## Configuration
 
@@ -21,26 +21,7 @@ Funnel progression is driven by **page view events**, matched on the screen name
 
 The screen name is read from the page view's `screen_name` attribute (falling back to the page name when that attribute is absent), so the names you list in `progressionScreenNames` are the `screen_name` values your application sends.
 
-Page view setting:
-
-| Setting | Maps to |
-| :-- | :-- |
-| `progressionScreenNames` | `stepComplete` (one per listed screen) |
-
-Custom event settings:
-
-| Setting | Maps to |
-| :-- | :-- |
-| `approvedEventName` | `approved` |
-| `pendingEventName` | `pending` |
-| `loggedInEventName` | `loggedIn` |
-| `accountCreatedEventName` | `accountCreated` |
-| `offerSavedEventName` | `offerSaved` |
-| `purchaseCompletedEventName` | `purchaseCompleted` |
-| `formSubmittedEventName` | `formSubmitted` |
-| `pendingSuccessEventName` | `pendingSuccess` |
-| `closeEventName` | `close` |
-| `removeLoadingOverlayEventName` | `removeLoadingOverlay` |
+`progressionScreenNames` lists the screens that emit `stepComplete`. Each custom-event setting maps an event name to the Pay+ signal of the same name: `approvedEventName` maps to `approved`, `purchaseCompletedEventName` maps to `purchaseCompleted`, and so on. The full list of fields, each with its description, appears in the connection settings in the mParticle dashboard.
 
 `initiated` is emitted automatically when the kit initializes. If no settings are provided, the kit applies a default mapping: each page view is treated as a funnel step, and a custom event named `conversion` is treated as the approval.
 

src/RoktPayPlus-Kit.ts

@@ -55,6 +55,7 @@ const SIGNALS = {
   PENDING_SUCCESS: 'pendingSuccess',
   CLOSE: 'close',
   REMOVE_LOADING_OVERLAY: 'removeLoadingOverlay',
+  GWP_APPROVED: 'gwpApproved',
 } as const;
 
 const DEFAULT_CONVERSION_EVENT_NAME = 'conversion';
@@ -71,6 +72,7 @@ const EVENT_SETTING_TO_SIGNAL: ReadonlyArray<{ setting: keyof RoktPayPlusKitSett
   { setting: 'pendingSuccessEventName', signal: SIGNALS.PENDING_SUCCESS },
   { setting: 'closeEventName', signal: SIGNALS.CLOSE },
   { setting: 'removeLoadingOverlayEventName', signal: SIGNALS.REMOVE_LOADING_OVERLAY },
+  { setting: 'gwpApprovedEventName', signal: SIGNALS.GWP_APPROVED },
 ];
 
 // ============================================================
@@ -91,6 +93,8 @@ interface RoktPayPlusKitSettings {
   closeEventName?: string;
   removeLoadingOverlayEventName?: string;
   conversionEventName?: string;
+  // Custom event name(s) that signal a gift-with-purchase conversion.
+  gwpApprovedEventName?: string;
 }
 
 interface KitConfig {

test/src/RoktPayPlus-Kit.spec.ts

@@ -121,6 +121,26 @@ describe('RoktPayPlusKit', () => {
     });
   });
 
+  describe('gwpApprovedEventName setting', () => {
+    it('emits gwpApproved for the configured custom event, with the event attributes as detail', () => {
+      const kit = new RoktPayPlusKit();
+      kit.init({ gwpApprovedEventName: 'Gift Purchase Completed' });
+      kit.process(customEvent('Gift Purchase Completed', { sku: 'gwp-123', amount: '49.99' }));
+      const gwp = ofType('gwpApproved');
+      expect(gwp.length).toBe(1);
+      expect(gwp[0].message.detail).toEqual({ sku: 'gwp-123', amount: '49.99' });
+      expect(gwp[0].message.trigger).toBe("logEvent('Gift Purchase Completed')");
+      expect(ofType('approved').length).toBe(0);
+    });
+
+    it('suppresses the default conversion fallback once gwpApprovedEventName is configured', () => {
+      const kit = new RoktPayPlusKit();
+      kit.init({ gwpApprovedEventName: 'Gift Purchase Completed' });
+      kit.process(customEvent('conversion'));
+      expect(ofType('approved').length).toBe(0);
+    });
+  });
+
   describe('embedding guard', () => {
     it('makes no postMessage calls when not framed (parent === self)', () => {
       // Restore the real window.parent so the page looks top-level (jsdom: parent === window).