@namiml/sdk-core 3.4.4-dev.202607072107 → 3.4.4-dev.202607072357

package/dist/index.cjs

@@ -98,7 +98,7 @@ const {
 // version — stamped by scripts/version.sh
 NAMI_SDK_VERSION: exports.NAMI_SDK_VERSION = "3.4.4", 
 // full package version including dev suffix — stamped by scripts/version.sh
-NAMI_SDK_PACKAGE_VERSION: exports.NAMI_SDK_PACKAGE_VERSION = "3.4.4-dev.202607072107", 
+NAMI_SDK_PACKAGE_VERSION: exports.NAMI_SDK_PACKAGE_VERSION = "3.4.4-dev.202607072357", 
 // environments
 PRODUCTION: exports.PRODUCTION = "production", DEVELOPMENT: exports.DEVELOPMENT = "development", 
 // error messages
@@ -61891,6 +61891,13 @@ const NamiHandoffTag = {
     BuySku: 'buysku',
     UserData: 'userdata',
 };
+/**
+ * True iff `tag` is a value of the customer-facing `NamiHandoffTag` vocabulary.
+ * Unknown tags are still delivered (pass-through) — this only drives a warning.
+ */
+function isKnownHandoffTag(tag) {
+    return Object.values(NamiHandoffTag).includes(tag);
+}
 /**
  * Permission types reportable through a handoff outcome.
  *
@@ -63988,6 +63995,8 @@ function validateForm(validators, formStates) {
     return errors;
 }
 
+/** Form field key convention for grouped handoffs: `<tag>::<payloadKey>`. */
+const HANDOFF_GROUP_KEY = /^([^:]+)::(.+)$/;
 class BasicNamiFlow {
     constructor(flowObject = {}) {
         this.id = flowObject.id ?? '';
@@ -64756,13 +64765,25 @@ class NamiFlow extends BasicNamiFlow {
             logger.warn("No formStates available for handoff sequence");
             return;
         }
-        const keys = Object.keys(formStates).sort();
+        const keys = Object.keys(formStates);
         if (keys.length === 0) {
             logger.warn("formStates is empty, no handoffs to perform");
             return;
         }
-        // filter keys where value === true
-        const eligibleKeys = keys.filter((k) => formStates[k] === true);
+        // Grouped path: at least one field uses the `tag::field` convention.
+        if (keys.some((k) => HANDOFF_GROUP_KEY.test(k))) {
+            const groups = this.buildHandoffGroups(formStates);
+            if (groups.length === 0) {
+                logger.info("No handoff groups after grouping");
+                this.manager.resume();
+                return;
+            }
+            this.activeHandoffSequence = { groups };
+            this.resumeNextHandoff();
+            return;
+        }
+        // Legacy path (unchanged): one handoff per true key, tag = field name.
+        const eligibleKeys = keys.sort().filter((k) => formStates[k] === true);
         if (eligibleKeys.length === 0) {
             logger.info("No eligible handoff keys after filtering");
             this.manager.resume();
@@ -64774,6 +64795,34 @@ class NamiFlow extends BasicNamiFlow {
         };
         this.resumeNextHandoff();
     }
+    /**
+     * Reduce a flat `formStates` map into one bucket per distinct handoff tag,
+     * using the `<tag>::<payloadKey>` field-key convention. Insertion order is
+     * preserved (group order = first-appearance). Reserved-prefixed tags are
+     * skipped so they never reach the host handler (NAM-1556). A group is kept
+     * only if at least one of its fields is `true` (a permission the user
+     * declined is not handed off); a kept group's payload rides verbatim,
+     * including its `false` fields.
+     */
+    buildHandoffGroups(formStates) {
+        const buckets = new Map();
+        for (const key of Object.keys(formStates)) {
+            const match = key.match(HANDOFF_GROUP_KEY);
+            if (!match)
+                continue;
+            const [, tag, field] = match;
+            if (tag.startsWith(RESERVED_HANDOFF_TAG_PREFIX)) {
+                logger.warn(`Ignoring reserved handoff group tag '${tag}'`);
+                continue;
+            }
+            if (!buckets.has(tag))
+                buckets.set(tag, {});
+            buckets.get(tag)[field] = formStates[key];
+        }
+        return Array.from(buckets, ([tag, data]) => ({ tag, data }))
+            .filter((group) => Object.values(group.data).some((value) => value === true))
+            .sort((a, b) => a.tag.localeCompare(b.tag));
+    }
     resumeNextHandoff() {
         const sequence = this.activeHandoffSequence;
         if (!sequence) {
@@ -64781,6 +64830,24 @@ class NamiFlow extends BasicNamiFlow {
             this.manager.resume();
             return;
         }
+        // Grouped path.
+        if ("groups" in sequence) {
+            if (sequence.groups.length === 0) {
+                logger.info("All handoffs in the sequence are complete");
+                this.activeHandoffSequence = null;
+                this.manager.resume();
+                return;
+            }
+            const next = sequence.groups.shift(); // safe: length > 0
+            if (!isKnownHandoffTag(next.tag)) {
+                logger.warn(`handoff group tag '${next.tag}' is outside the NamiHandoffTag vocabulary — passing through`);
+            }
+            this.activeHandoffSequence = sequence; // persist mutated groups
+            logger.debug(`Starting grouped handoff for '${next.tag}' → ${JSON.stringify(next.data)}`);
+            this.manager.deliverHandoff(next.tag, next.data);
+            return;
+        }
+        // Legacy path (unchanged).
         if (sequence.remainingKeys.length === 0) {
             logger.info("All handoffs in the sequence are complete");
             this.activeHandoffSequence = null;
@@ -64790,10 +64857,7 @@ class NamiFlow extends BasicNamiFlow {
         const nextKey = sequence.remainingKeys.shift(); // safe: length > 0
         const value = sequence.formStates[nextKey];
         logger.debug(`Starting handoff for ${nextKey} → ${String(value)}`);
-        // persist updated sequence (remainingKeys mutated)
         this.activeHandoffSequence = sequence;
-        // Route through the manager's single delivery point so v2 handlers get
-        // a working complete() for sequence-key handoffs too.
         this.manager.deliverHandoff(`${nextKey}`, undefined);
     }
 }

package/dist/index.d.ts

@@ -2249,6 +2249,11 @@ declare class NamiFlow extends BasicNamiFlow {
     activeHandoffSequence: {
         formStates: Record<string, boolean | string>;
         remainingKeys: string[];
+    } | {
+        groups: Array<{
+            tag: string;
+            data: Record<string, boolean | string>;
+        }>;
     } | null;
     currentScreenState: TPaywallContext | null;
     isPaused: boolean;
@@ -2357,6 +2362,16 @@ declare class NamiFlow extends BasicNamiFlow {
      */
     buildUserDataEnvelope(formId: string): NamiUserDataEnvelope;
     flowHandoffFormSequence(): void;
+    /**
+     * Reduce a flat `formStates` map into one bucket per distinct handoff tag,
+     * using the `<tag>::<payloadKey>` field-key convention. Insertion order is
+     * preserved (group order = first-appearance). Reserved-prefixed tags are
+     * skipped so they never reach the host handler (NAM-1556). A group is kept
+     * only if at least one of its fields is `true` (a permission the user
+     * declined is not handed off); a kept group's payload rides verbatim,
+     * including its `false` fields.
+     */
+    private buildHandoffGroups;
     resumeNextHandoff(): void;
 }
 

package/dist/index.mjs

@@ -96,7 +96,7 @@ const {
 // version — stamped by scripts/version.sh
 NAMI_SDK_VERSION = "3.4.4", 
 // full package version including dev suffix — stamped by scripts/version.sh
-NAMI_SDK_PACKAGE_VERSION = "3.4.4-dev.202607072107", 
+NAMI_SDK_PACKAGE_VERSION = "3.4.4-dev.202607072357", 
 // environments
 PRODUCTION = "production", DEVELOPMENT = "development", 
 // error messages
@@ -61889,6 +61889,13 @@ const NamiHandoffTag = {
     BuySku: 'buysku',
     UserData: 'userdata',
 };
+/**
+ * True iff `tag` is a value of the customer-facing `NamiHandoffTag` vocabulary.
+ * Unknown tags are still delivered (pass-through) — this only drives a warning.
+ */
+function isKnownHandoffTag(tag) {
+    return Object.values(NamiHandoffTag).includes(tag);
+}
 /**
  * Permission types reportable through a handoff outcome.
  *
@@ -63986,6 +63993,8 @@ function validateForm(validators, formStates) {
     return errors;
 }
 
+/** Form field key convention for grouped handoffs: `<tag>::<payloadKey>`. */
+const HANDOFF_GROUP_KEY = /^([^:]+)::(.+)$/;
 class BasicNamiFlow {
     constructor(flowObject = {}) {
         this.id = flowObject.id ?? '';
@@ -64754,13 +64763,25 @@ class NamiFlow extends BasicNamiFlow {
             logger.warn("No formStates available for handoff sequence");
             return;
         }
-        const keys = Object.keys(formStates).sort();
+        const keys = Object.keys(formStates);
         if (keys.length === 0) {
             logger.warn("formStates is empty, no handoffs to perform");
             return;
         }
-        // filter keys where value === true
-        const eligibleKeys = keys.filter((k) => formStates[k] === true);
+        // Grouped path: at least one field uses the `tag::field` convention.
+        if (keys.some((k) => HANDOFF_GROUP_KEY.test(k))) {
+            const groups = this.buildHandoffGroups(formStates);
+            if (groups.length === 0) {
+                logger.info("No handoff groups after grouping");
+                this.manager.resume();
+                return;
+            }
+            this.activeHandoffSequence = { groups };
+            this.resumeNextHandoff();
+            return;
+        }
+        // Legacy path (unchanged): one handoff per true key, tag = field name.
+        const eligibleKeys = keys.sort().filter((k) => formStates[k] === true);
         if (eligibleKeys.length === 0) {
             logger.info("No eligible handoff keys after filtering");
             this.manager.resume();
@@ -64772,6 +64793,34 @@ class NamiFlow extends BasicNamiFlow {
         };
         this.resumeNextHandoff();
     }
+    /**
+     * Reduce a flat `formStates` map into one bucket per distinct handoff tag,
+     * using the `<tag>::<payloadKey>` field-key convention. Insertion order is
+     * preserved (group order = first-appearance). Reserved-prefixed tags are
+     * skipped so they never reach the host handler (NAM-1556). A group is kept
+     * only if at least one of its fields is `true` (a permission the user
+     * declined is not handed off); a kept group's payload rides verbatim,
+     * including its `false` fields.
+     */
+    buildHandoffGroups(formStates) {
+        const buckets = new Map();
+        for (const key of Object.keys(formStates)) {
+            const match = key.match(HANDOFF_GROUP_KEY);
+            if (!match)
+                continue;
+            const [, tag, field] = match;
+            if (tag.startsWith(RESERVED_HANDOFF_TAG_PREFIX)) {
+                logger.warn(`Ignoring reserved handoff group tag '${tag}'`);
+                continue;
+            }
+            if (!buckets.has(tag))
+                buckets.set(tag, {});
+            buckets.get(tag)[field] = formStates[key];
+        }
+        return Array.from(buckets, ([tag, data]) => ({ tag, data }))
+            .filter((group) => Object.values(group.data).some((value) => value === true))
+            .sort((a, b) => a.tag.localeCompare(b.tag));
+    }
     resumeNextHandoff() {
         const sequence = this.activeHandoffSequence;
         if (!sequence) {
@@ -64779,6 +64828,24 @@ class NamiFlow extends BasicNamiFlow {
             this.manager.resume();
             return;
         }
+        // Grouped path.
+        if ("groups" in sequence) {
+            if (sequence.groups.length === 0) {
+                logger.info("All handoffs in the sequence are complete");
+                this.activeHandoffSequence = null;
+                this.manager.resume();
+                return;
+            }
+            const next = sequence.groups.shift(); // safe: length > 0
+            if (!isKnownHandoffTag(next.tag)) {
+                logger.warn(`handoff group tag '${next.tag}' is outside the NamiHandoffTag vocabulary — passing through`);
+            }
+            this.activeHandoffSequence = sequence; // persist mutated groups
+            logger.debug(`Starting grouped handoff for '${next.tag}' → ${JSON.stringify(next.data)}`);
+            this.manager.deliverHandoff(next.tag, next.data);
+            return;
+        }
+        // Legacy path (unchanged).
         if (sequence.remainingKeys.length === 0) {
             logger.info("All handoffs in the sequence are complete");
             this.activeHandoffSequence = null;
@@ -64788,10 +64855,7 @@ class NamiFlow extends BasicNamiFlow {
         const nextKey = sequence.remainingKeys.shift(); // safe: length > 0
         const value = sequence.formStates[nextKey];
         logger.debug(`Starting handoff for ${nextKey} → ${String(value)}`);
-        // persist updated sequence (remainingKeys mutated)
         this.activeHandoffSequence = sequence;
-        // Route through the manager's single delivery point so v2 handlers get
-        // a working complete() for sequence-key handoffs too.
         this.manager.deliverHandoff(`${nextKey}`, undefined);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namiml/sdk-core",
-  "version": "3.4.4-dev.202607072107",
+  "version": "3.4.4-dev.202607072357",
   "description": "Platform-agnostic core for the Nami SDK — business logic, API, types, and state management",
   "type": "module",
   "main": "./dist/index.cjs",