@cxpinsight/survey-spec 0.4.0 → 0.5.0

package/dist/validate.js

@@ -1,4 +1,25 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAnswer = validateAnswer;
+exports.validateAnswerCode = validateAnswerCode;
+exports.impliedChoices = impliedChoices;
+exports.impliedActions = impliedActions;
+exports.isDeferChoice = isDeferChoice;
+exports.safeActionHref = safeActionHref;
+exports.safeImageSrc = safeImageSrc;
+exports.impliedStepActions = impliedStepActions;
+exports.impliedEqualProminence = impliedEqualProminence;
+exports.canSwipeToDismiss = canSwipeToDismiss;
+exports.autoDismissMs = autoDismissMs;
+exports.deadlineCountdown = deadlineCountdown;
+exports.formatCountdown = formatCountdown;
+exports.outcomeFor = outcomeFor;
+exports.voiceUsable = voiceUsable;
+exports.rewardToShow = rewardToShow;
+exports.cardClickTarget = cardClickTarget;
+exports.cardHoverEffect = cardHoverEffect;
+exports.resolveAction = resolveAction;
+const messages_1 = require("./messages");
 /**
  * Answer validation — whether a respondent may submit.
  *
@@ -37,10 +58,6 @@
  * "that is not a valid email" — which sounds like the shape is wrong rather
  * than the field being blank.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateAnswer = validateAnswer;
-exports.impliedChoices = impliedChoices;
-exports.impliedActions = impliedActions;
 /**
  * Practical email format — matches what the HTML5 email validator accepts.
  * Not RFC 5322-strict: that regex is a page long and rejects addresses real
@@ -49,14 +66,25 @@ exports.impliedActions = impliedActions;
 const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 /** URL with a scheme. No guessing at whether `http://` was meant. */
 const URL_RE = /^https?:\/\/[\w.\-]+(?:\.[\w.\-]+)+(?:[/?#][^\s]*)?$/i;
-/** Null when the answer is valid; otherwise the message to show. */
+/**
+ * Null when the answer is valid; otherwise the ENGLISH message to show.
+ *
+ * The signature is unchanged on purpose — three renderers call this and expect
+ * a string. The wording now comes from one table (messages.ts) rather than
+ * being built inside the rules, so a renderer that wants another language calls
+ * `validateAnswerCode` and words the code itself.
+ */
 function validateAnswer(question, value) {
+    return (0, messages_1.wordMessage)(validateAnswerCode(question, value));
+}
+/** The same rules, as a code and its parameters. This is what a port implements. */
+function validateAnswerCode(question, value) {
     // BOTH spellings. The v1 vocabulary and the builder both emit `isRequired`,
     // and a renderer reading only `required` let a required question be submitted
     // blank while the other channels rejected it.
     const empty = isEmpty(question, value);
     if ((question.required || question.isRequired) && empty) {
-        return 'This field is required';
+        return { code: 'required', params: {} };
     }
     // An optional field left blank is valid. Complaining about the shape of an
     // answer nobody gave is noise.
@@ -147,24 +175,24 @@ function validateTextish(question, value) {
     const inputType = question.inputType
         || (question.type === 'email' ? 'email' : question.type === 'number' ? 'number' : undefined);
     if (inputType === 'email' && !EMAIL_RE.test(trimmed)) {
-        return 'Please enter a valid email address (e.g., you@example.com)';
+        return { code: 'format_email', params: {} };
     }
     if (inputType === 'url' && !URL_RE.test(trimmed)) {
-        return 'Please enter a full URL, including https://';
+        return { code: 'format_url', params: {} };
     }
     if (inputType === 'number' && Number.isNaN(Number(trimmed))) {
-        return 'Please enter a number';
+        return { code: 'format_number', params: {} };
     }
     if (inputType === 'tel' && !/^[\d\s+\-()]{3,}$/.test(trimmed)) {
         // Deliberately permissive. Country-specific phone validation inline is a
         // losing game that mostly rejects real numbers.
-        return 'Please enter a valid phone number';
+        return { code: 'format_tel', params: {} };
     }
     if (typeof question.maxLength === 'number' && trimmed.length > question.maxLength) {
-        return `Please keep this under ${question.maxLength} characters`;
+        return { code: 'max_length', params: { max: question.maxLength } };
     }
     if (typeof question.minLength === 'number' && trimmed.length < question.minLength) {
-        return `Please enter at least ${question.minLength} characters`;
+        return { code: 'min_length', params: { min: question.minLength } };
     }
     return null;
 }
@@ -177,10 +205,10 @@ function validateCheckbox(question, value) {
             : []);
     const count = choices.length;
     if (typeof question.minCount === 'number' && count < question.minCount) {
-        return `Please select at least ${question.minCount}`;
+        return { code: 'min_selected', params: { min: question.minCount } };
     }
     if (typeof question.maxCount === 'number' && count > question.maxCount) {
-        return `Please select at most ${question.maxCount}`;
+        return { code: 'max_selected', params: { max: question.maxCount } };
     }
     return null;
 }
@@ -188,10 +216,10 @@ function validateNumericRange(question, value) {
     if (typeof value !== 'number')
         return null;
     if (typeof question.minValue === 'number' && value < question.minValue) {
-        return `Must be at least ${question.minValue}`;
+        return { code: 'min_value', params: { min: question.minValue } };
     }
     if (typeof question.maxValue === 'number' && value > question.maxValue) {
-        return `Must be at most ${question.maxValue}`;
+        return { code: 'max_value', params: { max: question.maxValue } };
     }
     return null;
 }
@@ -202,9 +230,14 @@ function validateRules(question, value) {
     const str = typeof value === 'string' ? value : String(value ?? '');
     for (const r of rules) {
         const err = applyRule(r, str);
-        // The author's own message wins when they wrote one.
-        if (err)
-            return r.message || err;
+        if (!err)
+            continue;
+        // The author's own message wins when they wrote one — and it is NOT a code.
+        // It is prose the author typed, in whatever language they typed it, so it
+        // travels verbatim as a param and is never looked up in a wording table.
+        return typeof r.message === 'string' && r.message
+            ? { code: 'author_message', params: { text: r.message } }
+            : err;
     }
     return null;
 }
@@ -212,20 +245,20 @@ function applyRule(rule, str) {
     switch (rule.type) {
         case 'minLength':
             return typeof rule.value === 'number' && str.length < rule.value
-                ? `At least ${rule.value} characters` : null;
+                ? { code: 'rule_min_length', params: { min: rule.value } } : null;
         case 'maxLength':
             return typeof rule.value === 'number' && str.length > rule.value
-                ? `At most ${rule.value} characters` : null;
+                ? { code: 'rule_max_length', params: { max: rule.value } } : null;
         case 'min':
             return typeof rule.value === 'number' && Number(str) < rule.value
-                ? `Must be at least ${rule.value}` : null;
+                ? { code: 'min_value', params: { min: rule.value } } : null;
         case 'max':
             return typeof rule.value === 'number' && Number(str) > rule.value
-                ? `Must be at most ${rule.value}` : null;
+                ? { code: 'max_value', params: { max: rule.value } } : null;
         case 'email':
-            return EMAIL_RE.test(str) ? null : 'Please enter a valid email address';
+            return EMAIL_RE.test(str) ? null : { code: 'rule_email', params: {} };
         case 'url':
-            return URL_RE.test(str) ? null : 'Please enter a valid URL';
+            return URL_RE.test(str) ? null : { code: 'rule_url', params: {} };
         case 'pattern': {
             if (typeof rule.value !== 'string')
                 return null;
@@ -233,7 +266,7 @@ function applyRule(rule, str) {
                 // An unparseable pattern is an authoring mistake. Failing OPEN is
                 // deliberate: blocking every respondent on a survey because of a typo
                 // in a regex is worse than letting the answer through.
-                return new RegExp(rule.value).test(str) ? null : "Format doesn't match";
+                return new RegExp(rule.value).test(str) ? null : { code: 'rule_pattern', params: {} };
             }
             catch {
                 return null;
@@ -266,13 +299,13 @@ function validateImplied(question, value) {
     if (!required)
         return null;
     if (chosen === null || chosen === undefined || chosen === '') {
-        return 'Please choose an option';
+        return { code: 'choose_option', params: {} };
     }
     // A value that is not one of the offered choices means the answer came from
     // somewhere other than the buttons — a stale client, or a crafted payload.
     const choices = impliedChoices(question);
     if (choices.length && choices.indexOf(String(chosen)) === -1) {
-        return 'Please choose an option';
+        return { code: 'choose_option', params: {} };
     }
     return null;
 }
@@ -318,9 +351,446 @@ function impliedActions(question) {
             const o = c;
             const value = o.value != null ? String(o.value) : String(o.label ?? o.text ?? '');
             const label = String(o.label ?? o.text ?? o.value ?? '');
-            if (value !== '' || label !== '')
-                out.push({ value, label: label || value });
+            // WHERE THE ACTION TAKES THEM. Carried here because it was being dropped:
+            // the templates set `action: { type: 'url', value }` on a choice, this
+            // function returned only {value, label}, and so a "Resume" button on an
+            // abandoned-cart nudge recorded the answer and left the customer exactly
+            // where they were — which is the one thing that nudge exists to change.
+            const href = safeActionHref(o.action);
+            if (value !== '' || label !== '') {
+                const entry = href ? { value, label: label || value, href } : { value, label: label || value };
+                // "Remind me later" — see isDeferChoice. Carried through because a
+                // renderer cannot tell a defer from a decline by looking at the label,
+                // and treating one as the other is the difference between a snooze and
+                // a permanent no.
+                if (o.defer === true)
+                    entry.defer = true;
+                out.push(entry);
+            }
         }
     }
     return out;
 }
+/**
+ * Is this choice a "Remind me later" — a deferral rather than an answer?
+ *
+ * A deferring choice CLOSES the surface AND RECORDS A SKIP, and deliberately
+ * does not submit. That distinction is the whole feature: a skip feeds
+ * cooldownOnSkip and maxSkips, so the interaction comes back after the wait and
+ * gives up after the last try. A submission feeds maxSubmissions, which means
+ * "they decided" — and a person who asked to be reminded has decided nothing.
+ *
+ * Without this, "Remind me later" could only be built as an ordinary choice,
+ * which recorded an answer and retired the interaction for good: the one button
+ * whose entire purpose is to bring it back was the one that guaranteed it never
+ * would.
+ *
+ * NEVER ON A COMPLIANCE SURFACE, and not as a matter of taste. must-show
+ * bypasses the frequency gate entirely while unsatisfied, so a deferral there
+ * would be inert — the takeover would reappear immediately and the button would
+ * be a visible lie. If someone may genuinely postpone, the interaction is not
+ * must-show, and that is the setting to change.
+ */
+function isDeferChoice(choice, interactionType) {
+    if (!choice || typeof choice !== 'object')
+        return false;
+    if (String(interactionType || '').toLowerCase() === 'comply')
+        return false;
+    return choice.defer === true;
+}
+/**
+ * The navigable target of a choice's `action`, or undefined.
+ *
+ * Only `type: 'url'` navigates today, and only to a scheme that cannot execute
+ * script in the host page. `javascript:` and `data:` are the two that can, so
+ * an author-supplied (or API-supplied) action is not a place to be permissive:
+ * a survey definition travels from the server into a customer's own site, and a
+ * URL that runs code there is an XSS vector wearing a button.
+ *
+ * Relative paths and app deep-link schemes are allowed — a mobile nudge that
+ * opens `myapp://cart` is the point of the feature.
+ */
+function safeActionHref(action) {
+    if (!action || typeof action !== 'object')
+        return undefined;
+    const a = action;
+    if (String(a.type || '').toLowerCase() !== 'url')
+        return undefined;
+    const v = typeof a.value === 'string' ? a.value.trim() : '';
+    if (!v)
+        return undefined; // '' = not configured yet
+    // Reject anything whose scheme could execute in the host document.
+    const scheme = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(v);
+    if (scheme) {
+        const s = scheme[1].toLowerCase();
+        if (s === 'javascript' || s === 'data' || s === 'vbscript' || s === 'file')
+            return undefined;
+    }
+    return v;
+}
+/**
+ * The `src` for an image the author placed in a survey, or '' to draw nothing.
+ *
+ * SEPARATE FROM safeActionHref ON PURPOSE. That one guards a NAVIGATION target,
+ * where `data:` is an XSS vector wearing a button — a URL the host page is told
+ * to follow. This guards an IMAGE SOURCE, which the host page only ever
+ * decodes as pixels, and `data:image/...;base64,` is exactly how the builder
+ * stores an uploaded picture: there is no file host in the product, so an
+ * upload becomes a data URI or it becomes nothing.
+ *
+ * Collapsing the two was a real bug, not a hypothetical one. The web SDK ran
+ * every image through its link guard, which allows only http/https/mailto/tel,
+ * so every uploaded offer image was rewritten to `src=""` and vanished —
+ * on the web and mobile preview frames, which both run the SDK, while the link
+ * surface (React, no guard) showed it. An author saw their picture appear on
+ * one surface out of three and had no way to tell why.
+ *
+ * `<img>` is a non-scripting context: an SVG loaded through it cannot run its
+ * own script, so `data:image/*` is safe here in a way it is not on an href.
+ * Everything else with a scheme is still refused — `data:text/html` most of
+ * all, which is the one that would actually execute.
+ */
+function safeImageSrc(url) {
+    const raw = String(url == null ? '' : url).trim();
+    if (!raw)
+        return '';
+    // Control characters are how a scheme gets smuggled past a naive check
+    // ("java\tscript:"), so strip them before looking at it.
+    const probe = raw.replace(/[\u0000-\u0020]/g, '');
+    const scheme = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(probe);
+    if (!scheme)
+        return raw; // relative path — the host resolves it
+    const s = scheme[1].toLowerCase();
+    if (s === 'http' || s === 'https')
+        return raw;
+    // Only image payloads, and only ones that declare themselves as such.
+    if (s === 'data' && /^data:image\/[a-zA-Z0-9.+-]+[;,]/i.test(probe))
+        return raw;
+    return '';
+}
+/**
+ * The action buttons for a STEP, or [] for an ordinary step.
+ *
+ * A Notify, Offer or Comply interaction's buttons are its ANSWER — "Activate
+ * discount" and "No thanks" are the two things the respondent can say, not
+ * decoration beside a Next button. So a step that ends in an implied question
+ * has NO Next and NO Submit: pressing an action IS the submission.
+ *
+ * The rule lives here because all three renderers have to agree on it. When
+ * they didn't, the web SDK replaced Next with the actions while the React and
+ * React Native renderers drew the actions AND kept Submit — the respondent saw
+ * "Resume" and "Submit" stacked, and pressing Resume did nothing but tick a
+ * radio nobody could see.
+ *
+ * The LAST question decides. A step is allowed to carry content above the
+ * actions (a paragraph of terms, an image); what closes it is what turns it
+ * into a decision.
+ *
+ * Never returns an empty list for an implied step: an implied question with no
+ * choices would be a dead end — no buttons and no way out — so one neutral
+ * action beats a surface the respondent cannot leave.
+ */
+function impliedStepActions(questions) {
+    if (!Array.isArray(questions) || questions.length === 0)
+        return [];
+    const last = questions[questions.length - 1];
+    if (!last || String(last.type || '').toLowerCase() !== 'implied')
+        return [];
+    try {
+        const acts = impliedActions(last) || [];
+        return acts.length ? acts : [{ value: 'acknowledged', label: 'Continue' }];
+    }
+    catch {
+        return [{ value: 'acknowledged', label: 'Continue' }];
+    }
+}
+/**
+ * Should this step's actions render with EQUAL PROMINENCE?
+ *
+ * A consent choice is not a call to action with an escape hatch. When accept is
+ * a filled accent button and decline is a quiet outline, the design is doing
+ * persuasion work on a decision that must be freely given — the pattern
+ * regulators name when they talk about consent dark patterns, and the reason
+ * `equalProminence` exists on the question.
+ *
+ * It was being SET by the compliance templates and read by nothing, so both
+ * shipped with a filled "I agree" beside a ghosted "Decline".
+ *
+ * Same "last question decides" rule as impliedStepActions, so the two can never
+ * disagree about which question they are talking about.
+ */
+function impliedEqualProminence(questions) {
+    if (!Array.isArray(questions) || questions.length === 0)
+        return false;
+    const last = questions[questions.length - 1];
+    if (!last || String(last.type || '').toLowerCase() !== 'implied')
+        return false;
+    return last.equalProminence === true;
+}
+/**
+ * May this surface be dismissed by SWIPING it away?
+ *
+ * A push notification on a phone has no ✕. It slides down, and it leaves when
+ * you flick it. Removing the close button without providing the gesture would
+ * just make it untouchable, so the two decisions are one decision and it lives
+ * here rather than three times over.
+ *
+ * THE FULLSCREEN EXCLUSION IS THE WHOLE POINT. A compliance takeover ALSO sets
+ * showClose:false — for the opposite reason: it must not be escapable. Deriving
+ * "swipeable" from "has no close button" alone would hand every terms prompt and
+ * age check a flick-to-skip gesture, which is precisely the thing that makes it
+ * a blocking surface. So a swipe needs a POPUP, and a `mustShow` interaction is
+ * never swipeable whatever its mode.
+ *
+ * @param display  The resolved display slice for THIS surface (already picked
+ *                 per platform — a web slice is not a mobile one).
+ * @param delivery The survey's delivery policy, for the mustShow veto.
+ */
+function canSwipeToDismiss(display, delivery) {
+    if (!display)
+        return false;
+    if (delivery && delivery.mustShow === true)
+        return false;
+    const mode = String(display.mode || 'popup').toLowerCase();
+    if (mode !== 'popup')
+        return false; // fullscreen / modal never swipe
+    return display.showClose === false; // the gesture REPLACES the ✕
+}
+/**
+ * How long before this surface dismisses ITSELF, in ms. 0 = never.
+ *
+ * A push notification leaves on its own; that is most of what separates it from
+ * a dialog. `autoDismiss` was named in the interaction profile as a control the
+ * notify purpose leads with, and then existed nowhere else — no field, no UI, no
+ * timer — so every notification sat there until someone dealt with it.
+ *
+ * TWO SURFACES MUST NEVER SELF-DISMISS, and both would be silent disasters:
+ *
+ *  - A LINK IS THE PAGE. Auto-dismissing there does not tidy a banner away, it
+ *    blanks the page the respondent deliberately opened. The caller passes the
+ *    resolved slice, so a link slice simply never carries the value — but the
+ *    mode check below makes it structural rather than a matter of nobody
+ *    having set it.
+ *  - A BLOCKING SURFACE. Fullscreen compliance and anything `mustShow` exist to
+ *    be answered; a timer that clears them is an escape hatch with a stopwatch.
+ *
+ * Clamped to 2s minimum: a notification that vanishes faster than it can be
+ * read is worse than one that never appeared, and it is the accessibility
+ * complaint that gets filed about auto-dismissing content.
+ */
+function autoDismissMs(display, delivery) {
+    if (!display)
+        return 0;
+    if (delivery && delivery.mustShow === true)
+        return 0;
+    if (String(display.mode || 'popup').toLowerCase() !== 'popup')
+        return 0;
+    const raw = display.autoDismiss;
+    const n = typeof raw === 'number' ? raw : typeof raw === 'string' ? Number(raw) : NaN;
+    if (!Number.isFinite(n) || n <= 0)
+        return 0;
+    // Authors think in seconds; anything under 100 is read as seconds.
+    const ms = n < 100 ? n * 1000 : n;
+    return Math.max(2000, Math.round(ms));
+}
+/**
+ * The countdown to show on an interaction, or null.
+ *
+ * THE TIMER IS THE DEADLINE — it is not a separate number an author types.
+ * That identity is the whole design: the survey's `endDate` is what the
+ * eligibility gate already enforces, so a countdown derived from it cannot
+ * outlive the thing it counts down to. An independently-authored timer can, and
+ * an offer whose clock hits zero while the discount still works (or keeps
+ * ticking after it stops) is the expired-deadline dark pattern the validity
+ * gate exists to prevent.
+ *
+ * Returns null when there is no deadline, when it has already passed (the gate
+ * stops serving then anyway), or when the surface has not asked to show one.
+ * Never invents a deadline.
+ */
+function deadlineCountdown(survey, display, now) {
+    if (!survey || !display || display.showDeadline !== true)
+        return null;
+    const raw = survey.endDate;
+    if (!raw)
+        return null;
+    const end = raw instanceof Date ? raw.getTime() : Date.parse(String(raw));
+    if (!Number.isFinite(end))
+        return null;
+    const ms = end - (typeof now === 'number' ? now : Date.now());
+    if (ms <= 0)
+        return null; // over — show nothing, not "0:00"
+    return { ms, text: formatCountdown(ms) };
+}
+/** "3d 4h" · "4h 12m" · "12m 30s" · "30s" — two units at most, never a wall of zeros. */
+function formatCountdown(ms) {
+    const total = Math.max(0, Math.floor(ms / 1000));
+    const d = Math.floor(total / 86400);
+    const h = Math.floor((total % 86400) / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    const s = total % 60;
+    if (d > 0)
+        return h > 0 ? `${d}d ${h}h` : `${d}d`;
+    if (h > 0)
+        return m > 0 ? `${h}h ${m}m` : `${h}h`;
+    if (m > 0)
+        return s > 0 ? `${m}m ${s}s` : `${m}m`;
+    return `${s}s`;
+}
+/**
+ * Decide the ending.
+ *
+ * The compliance branch is the one with teeth. Accepting is NOT the same as
+ * being cleared: when a human has to review an identity document, letting the
+ * customer through on submit tells them they are finished when they are not,
+ * and defeats the check. So `reviewRequired` holds the surface up, and a
+ * decline holds it too unless the author chose otherwise — a compliance
+ * surface you get past by saying no is not a compliance surface.
+ */
+function outcomeFor(input) {
+    const purpose = String(input.interactionType || 'ask').toLowerCase();
+    const yes = input.affirmative !== false;
+    if (purpose === 'notify')
+        return yes ? 'navigate' : 'dismiss';
+    if (purpose === 'offer') {
+        if (!yes)
+            return 'dismiss';
+        // 'link' sends them somewhere it is already applied; the others have
+        // something to show.
+        return String(input.reward?.type || '') === 'link' ? 'navigate' : 'fulfil';
+    }
+    if (purpose === 'comply') {
+        if (!yes) {
+            return String(input.compliance?.onDecline || 'block') === 'block' ? 'hold' : 'dismiss';
+        }
+        return input.compliance?.reviewRequired === true ? 'hold' : 'unblock';
+    }
+    // 'ask' and every customer-defined purpose. A thank-you is the safe default
+    // for something we do not recognise: it acknowledges without promising.
+    return 'thanks';
+}
+/**
+ * Can voice mode do anything on this step?
+ *
+ * A notification, an offer and a compliance takeover ask one question whose
+ * answer is which button you pressed. A microphone on that surface offers to
+ * transcribe nothing — it was showing up on offers because `voiceMode` was
+ * merely DEFAULTED off on newer templates, so any interaction created before
+ * that, or through the API, still rendered one.
+ *
+ * Structural, not a default: if the step has no answerable input, voice is off
+ * regardless of what the survey or the application says.
+ */
+function voiceUsable(questions) {
+    if (!Array.isArray(questions) || questions.length === 0)
+        return false;
+    return questions.some((q) => {
+        const t = String(q.type || '').toLowerCase();
+        // Display-only types answer nothing; implied is answered by pressing.
+        return t !== 'implied' && t !== 'html' && t !== 'content'
+            && t !== 'image' && t !== 'expression' && t !== 'pagebreak';
+    });
+}
+/** The reward, ready to show — or null when there is nothing to hand over. */
+function rewardToShow(survey) {
+    const r = survey?.reward;
+    if (!r || !r.type)
+        return null;
+    const type = String(r.type);
+    const value = r.value == null ? '' : String(r.value);
+    // 'automatic' has nothing to display — the host app applies it on the
+    // outcome — so there is no panel to render.
+    if (type === 'automatic')
+        return null;
+    if (!value)
+        return null;
+    return {
+        type,
+        value,
+        whereValid: r.whereValid == null ? '' : String(r.whereValid),
+        // THE INTERACTION'S OWN END DATE. Not a second field that could disagree
+        // with the countdown the customer just watched.
+        expiresAt: survey?.endDate ? new Date(String(survey.endDate)).toISOString() : null,
+    };
+}
+/**
+ * Where clicking the CARD ITSELF should take someone, or null.
+ *
+ * People tap the message, not the button — so a notification's whole card is
+ * the click target. This was derived behaviour ("one action that has a link");
+ * it is now something an author sets, with the derived rule as the default so
+ * nothing that already worked stops working.
+ *
+ * THE TWO-ACTION VETO IS ABSOLUTE and not an author's to override. On a card
+ * offering accept and decline, a stray click anywhere would have to mean one of
+ * them — and on a consent surface that would manufacture agreement from a
+ * mis-tap. So a card is only ever clickable when it asks for exactly one thing.
+ */
+function cardClickTarget(display, actions) {
+    const acts = Array.isArray(actions) ? actions : [];
+    if (acts.length !== 1)
+        return null; // never on a choice
+    if (display?.cardClickable === false)
+        return null; // explicitly switched off
+    // An author-set destination wins, and goes through the same scheme guard as
+    // any other action target — this navigates inside the customer's own page.
+    const own = safeActionHref({ type: 'url', value: display?.cardHref });
+    return own || acts[0].href || null;
+}
+/** Hover treatment for a clickable card. Pointer devices only. */
+function cardHoverEffect(display) {
+    const v = String(display?.hoverEffect || '').toLowerCase();
+    return v === 'lift' || v === 'glow' || v === 'tint' ? v : 'none';
+}
+/**
+ * Resolve an action against a variable context.
+ *
+ * `interpolate` is supplied by the caller because each renderer already owns
+ * one, with its own context — the web SDK's reads the trigger event and device
+ * signals, the link renderer's reads URL params and answers. Passing the
+ * function keeps one rule here and one context there.
+ *
+ * INTERPOLATE FIRST, THEN CHECK THE SCHEME. A variable is data from outside —
+ * a URL parameter, a trait, an event field — so validating the template and
+ * then substituting would let `{{next}}` smuggle in `javascript:`. safeActionHref
+ * runs on the FINISHED string.
+ */
+function resolveAction(action, interpolate = (s) => s) {
+    if (!action || typeof action !== 'object')
+        return null;
+    const raw = String(action.type || 'url').toLowerCase();
+    const kind = raw === 'event' || raw === 'webhook' ? raw : 'url';
+    const template = typeof action.value === 'string' ? action.value : '';
+    const substituted = template ? interpolate(template) : '';
+    const href = substituted ? safeActionHref({ type: 'url', value: substituted }) || null : null;
+    const payload = {};
+    const p = action.payload;
+    if (p && typeof p === 'object' && !Array.isArray(p)) {
+        for (const [k, v] of Object.entries(p)) {
+            if (!k)
+                continue;
+            const tpl = String(v == null ? '' : v);
+            const out = interpolate(tpl);
+            // A reference that did not resolve is DROPPED, never sent.
+            //
+            // Two shapes of the same problem. Some interpolators leave the token in
+            // place, and "{{eventData.orderId}}" arriving at a CRM is indistinguishable
+            // from a real id, so it gets stored as one. Others — the web SDK's among
+            // them — substitute an empty string, which is worse: the field looks
+            // answered and says nothing. Since we cannot tell "resolved to empty"
+            // from "never resolved", a template that produces nothing is omitted, and
+            // the receiving system sees an absent field rather than a false one.
+            if (/\{\{.*\}\}/.test(out))
+                continue;
+            if (!out && /\{\{.*\}\}/.test(tpl))
+                continue;
+            payload[k] = out;
+        }
+    }
+    const eventName = typeof action.eventName === 'string' && action.eventName.trim()
+        ? action.eventName.trim() : null;
+    // Nothing to do: no destination, no event name, no payload.
+    if (!href && !eventName && Object.keys(payload).length === 0)
+        return null;
+    return { kind, href, eventName, payload };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cxpinsight/survey-spec",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The survey specification the renderers share \u2014 expression evaluation first. Source of truth for behaviour that must be identical on web, links and mobile.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",