@product7/feedback-sdk 1.6.9 → 1.7.1

package/dist/docs/survey-test-cases.md

@@ -0,0 +1,398 @@
+# Survey Widget — QA Test Cases
+
+## Overview
+This document covers manual test cases for verifying the survey widget functionality across all supported survey types (NPS, CSAT, CES, Custom, and Multi-page).
+
+---
+
+## Prerequisites
+
+- SDK is initialized with a valid `workspace` and `userContext`
+- `init()` has been called successfully (session token received)
+- Browser DevTools open to monitor network requests and console
+
+---
+
+## Test Environment Setup
+
+```js
+const sdk = new FeedbackSDK({
+  workspace: 'your-workspace',
+  userContext: { user_id: 'qa_user_01', email: 'qa@example.com' }
+});
+await sdk.init();
+```
+
+---
+
+## TC-01: NPS Survey — Basic Display
+
+**Objective:** Verify NPS survey renders correctly with 11-point scale.
+
+**Steps:**
+1. Call `sdk.showSurvey({ surveyType: 'nps', ratingScale: 11, title: 'How likely are you to recommend us?', lowLabel: 'Not likely', highLabel: 'Very likely' })`
+2. Observe the survey widget on screen
+
+**Expected Results:**
+- [ ] Survey widget appears at the configured position (default: bottom-right)
+- [ ] Title text is displayed: "How likely are you to recommend us?"
+- [ ] 11 score buttons are shown, numbered 0 through 10
+- [ ] "Not likely" label appears below the leftmost button
+- [ ] "Very likely" label appears below the rightmost button
+- [ ] A close (✕) button is visible in the top-right corner of the widget
+
+---
+
+## TC-02: NPS Survey — Score Selection
+
+**Objective:** Verify score buttons highlight correctly on selection.
+
+**Steps:**
+1. Show NPS survey (as in TC-01)
+2. Click score button **7**
+3. Click score button **9**
+
+**Expected Results:**
+- [ ] After clicking 7: button 7 is visually highlighted/selected
+- [ ] After clicking 9: button 9 is highlighted, button 7 is no longer highlighted
+- [ ] Only one button is selected at a time
+
+---
+
+## TC-03: NPS Survey — Submission
+
+**Objective:** Verify NPS survey submits the selected score.
+
+**Steps:**
+1. Show NPS survey with `showSubmitButton: true` and a valid `surveyId`
+2. Click score button **8**
+3. Click the **Submit** button
+4. Observe network tab
+
+**Expected Results:**
+- [ ] A POST request is sent to `/widget/surveys/{surveyId}/responses`
+- [ ] Request payload contains `rating: 8`
+- [ ] Survey widget closes after submission
+- [ ] A success notification ("Thank you for your feedback!") appears briefly
+- [ ] `survey:submitted` event is fired (verify in console with `sdk.on('survey:submitted', console.log)`)
+
+---
+
+## TC-04: NPS Survey — Submit Without Score
+
+**Objective:** Verify error message when submitting with no score selected.
+
+**Steps:**
+1. Show NPS survey with `showSubmitButton: true`
+2. Do NOT click any score button
+3. Click the **Submit** button
+
+**Expected Results:**
+- [ ] Error message "Please select a rating" appears inside the widget
+- [ ] Survey does NOT close
+- [ ] No API request is made
+- [ ] Error disappears after ~3 seconds
+
+---
+
+## TC-05: NPS Survey — Auto-submit on Select
+
+**Objective:** Verify survey auto-submits when `autoSubmitOnSelect: true`.
+
+**Steps:**
+1. Call `sdk.showSurvey({ surveyType: 'nps', autoSubmitOnSelect: true, surveyId: 'survey-id' })`
+2. Click any score button
+
+**Expected Results:**
+- [ ] Survey submits immediately upon clicking a score (no submit button click needed)
+- [ ] POST request is sent with the selected score
+- [ ] Survey closes and success notification shows
+
+---
+
+## TC-06: CSAT Survey — Display and Selection
+
+**Objective:** Verify CSAT survey renders emoji buttons correctly.
+
+**Steps:**
+1. Call `sdk.showSurvey({ surveyType: 'csat', title: 'How satisfied are you?' })`
+2. Click the 4th emoji (😊)
+
+**Expected Results:**
+- [ ] 5 emoji buttons are displayed (😞 😟 😐 🙂 😄)
+- [ ] Clicked emoji is visually selected/highlighted
+- [ ] Other emojis are deselected
+- [ ] Score corresponds to position (1–5)
+
+---
+
+## TC-07: CES Survey — Display and Selection
+
+**Objective:** Verify CES survey renders effort scale buttons.
+
+**Steps:**
+1. Call `sdk.showSurvey({ surveyType: 'ces', title: 'How easy was it?' })`
+2. Click **Easy**
+
+**Expected Results:**
+- [ ] 5 buttons displayed: Very Difficult / Difficult / Neutral / Easy / Very Easy
+- [ ] Clicked button is highlighted
+- [ ] Other buttons are deselected
+
+---
+
+## TC-08: Survey with Feedback Text Input
+
+**Objective:** Verify optional feedback textarea appears and value is submitted.
+
+**Steps:**
+1. Show any survey with `showFeedbackInput: true` and `showSubmitButton: true`
+2. Select a score
+3. Type "Great product!" in the feedback textarea
+4. Click Submit
+
+**Expected Results:**
+- [ ] Textarea is visible below the score selection
+- [ ] Typed text appears in the textarea
+- [ ] Submitted payload includes `feedback: "Great product!"`
+
+---
+
+## TC-09: Survey Dismiss — Close Button
+
+**Objective:** Verify close button dismisses the survey.
+
+**Steps:**
+1. Show any survey
+2. Click the ✕ (close) button
+
+**Expected Results:**
+- [ ] Survey widget fades out and is removed from the DOM
+- [ ] `survey:dismissed` event is fired
+- [ ] If `onDismiss` callback was provided, it is called
+- [ ] If a valid `surveyId` was set, a POST request is sent to `/widget/surveys/{surveyId}/dismiss`
+
+---
+
+## TC-10: Survey Dismiss — Escape Key
+
+**Objective:** Verify pressing Escape closes the survey.
+
+**Steps:**
+1. Show any survey
+2. Press the **Escape** key on the keyboard
+
+**Expected Results:**
+- [ ] Survey closes (same behaviour as TC-09)
+- [ ] `survey:dismissed` event fires
+
+---
+
+## TC-11: Survey — Disabled State
+
+**Objective:** Verify survey is suppressed when `enabled: false`.
+
+**Steps:**
+1. Call `sdk.showSurvey({ surveyType: 'nps', enabled: false })`
+
+**Expected Results:**
+- [ ] No survey widget appears in the DOM
+- [ ] `showSurvey()` returns `null`
+- [ ] `survey:suppressed` event is fired with `reason: 'disabled'`
+
+---
+
+## TC-12: Survey — Position Variants
+
+**Objective:** Verify survey renders in each supported position.
+
+**Steps:**
+1. Test each position: `bottom-right`, `bottom-left`, `center`
+2. Call `sdk.showSurvey({ surveyType: 'nps', position: '<position>' })`
+
+**Expected Results:**
+| Position | Expected Appearance |
+|---|---|
+| `bottom-right` | Widget anchored to bottom-right corner |
+| `bottom-left` | Widget anchored to bottom-left corner |
+| `center` | Widget centered on screen with backdrop overlay |
+
+- [ ] For `center`: backdrop overlay is displayed behind the widget
+- [ ] Clicking the backdrop (center mode) closes the survey
+
+---
+
+## TC-13: Survey — Theme Variants
+
+**Objective:** Verify light and dark themes apply correctly.
+
+**Steps:**
+1. Test `theme: 'light'` and `theme: 'dark'`
+
+**Expected Results:**
+- [ ] Light theme: white/light background, dark text
+- [ ] Dark theme: dark background, light text
+- [ ] Theme class is applied to the survey element
+
+---
+
+## TC-14: Multi-page Survey — Navigation
+
+**Objective:** Verify multi-page survey navigates between pages correctly.
+
+**Setup:**
+```js
+sdk.showSurvey({
+  surveyId: 'multi-page-id',
+  pages: [
+    { id: 'p1', type: 'rating', title: 'Rate our product', position: 0, ratingConfig: { scale: 5 } },
+    { id: 'p2', type: 'text', title: 'Any comments?', position: 1 },
+  ]
+});
+```
+
+**Steps:**
+1. Observe page 1
+2. Click a rating button
+3. Click **Next**
+4. Observe page 2
+5. Click **Back**
+6. Observe page 1 again
+
+**Expected Results:**
+- [ ] Page 1 shows "Page 1 of 2" progress indicator
+- [ ] Action button on page 1 reads "Next"
+- [ ] After clicking Next: page 2 loads, progress shows "Page 2 of 2"
+- [ ] Page 2 has a **Back** button
+- [ ] Action button on page 2 reads "Submit"
+- [ ] After clicking Back: page 1 is shown again
+
+---
+
+## TC-15: Multi-page Survey — Validation
+
+**Objective:** Verify each page validates input before advancing.
+
+**Steps (Rating page):**
+1. Display multi-page survey on page 1 (rating type)
+2. Click **Next** without selecting a rating
+
+**Expected Results:**
+- [ ] Error message "Please select a rating" appears
+- [ ] Survey does NOT advance to page 2
+
+**Steps (Text page):**
+1. Advance to a text-type page
+2. Click **Submit** without entering any text
+
+**Expected Results:**
+- [ ] Error message "Please enter an answer" appears
+- [ ] Survey does NOT submit
+
+**Steps (Multiple choice page):**
+1. Advance to a multiple-choice page
+2. Click **Submit** without selecting any option
+
+**Expected Results:**
+- [ ] Error message "Please select an option" appears
+
+---
+
+## TC-16: Multi-page Survey — Full Submission
+
+**Objective:** Verify complete multi-page survey submits all page answers.
+
+**Steps:**
+1. Display the multi-page survey (TC-14 setup)
+2. On page 1: select a rating, click **Next**
+3. On page 2: type a comment, click **Submit**
+4. Check network request
+
+**Expected Results:**
+- [ ] POST to `/widget/surveys/{surveyId}/responses` is made
+- [ ] Payload `answers.page_answers` contains entries for both pages
+- [ ] Success notification appears after submission
+
+---
+
+## TC-17: getActiveSurveys() — Fetch and Display
+
+**Objective:** Verify active surveys can be fetched and shown programmatically.
+
+**Steps:**
+1. Call `const surveys = await sdk.getActiveSurveys()`
+2. Log result to console
+3. Call `sdk.showSurveyById(surveys[0].surveyId)`
+
+**Expected Results:**
+- [ ] `getActiveSurveys()` returns an array of survey objects
+- [ ] Each survey has `surveyId`, `surveyType`, `title` fields
+- [ ] `showSurveyById()` successfully renders the matching survey
+- [ ] Correct survey type is shown (NPS/CSAT/CES matches the fetched type)
+
+---
+
+## TC-18: showSurveyById() — Survey Not Found
+
+**Objective:** Verify error handling when survey ID doesn't exist.
+
+**Steps:**
+1. Call `await sdk.showSurveyById('nonexistent-id')`
+
+**Expected Results:**
+- [ ] Promise rejects with an error message containing "not found"
+- [ ] No survey widget appears in the DOM
+
+---
+
+## TC-19: Survey — onSubmit Callback
+
+**Objective:** Verify `onSubmit` callback receives the correct response object.
+
+**Steps:**
+1. Call:
+```js
+sdk.showSurvey({
+  surveyType: 'nps',
+  ratingScale: 11,
+  showSubmitButton: true,
+  onSubmit: (response) => console.log('onSubmit:', response)
+});
+```
+2. Select score 9 and click Submit
+3. Check console output
+
+**Expected Results:**
+- [ ] `onSubmit` is called once
+- [ ] `response.type` is `'nps'`
+- [ ] `response.score` is `9`
+- [ ] `response.timestamp` is a valid ISO date string
+
+---
+
+## TC-20: Survey — SDK Not Initialized Guard
+
+**Objective:** Verify SDK throws when survey methods are called before `init()`.
+
+**Steps:**
+1. Create SDK instance but do NOT call `init()`
+2. Call `sdk.showSurvey({ surveyType: 'nps' })`
+
+**Expected Results:**
+- [ ] Error is thrown: "SDK must be initialized before showing surveys. Call init() first."
+- [ ] No network requests are made
+
+---
+
+## Regression Checklist
+
+After any change to survey code, verify:
+
+- [ ] All 4 survey types render without console errors (NPS, CSAT, CES, Custom)
+- [ ] Score selection works for each type
+- [ ] Submit sends correct payload to the API
+- [ ] Dismiss/close cleans up the DOM (no lingering elements)
+- [ ] Multi-page navigation works forward and backward
+- [ ] `survey:shown`, `survey:submitted`, `survey:dismissed`, `survey:suppressed` events all fire at the right time
+- [ ] `autoSubmitOnSelect: true` does not show submit button
+- [ ] `enabled: false` prevents the survey from rendering

package/dist/feedback-sdk.js

@@ -179,31 +179,172 @@
 	const MOCK_SURVEYS = [
 		{
 			id: 'mock_nps_survey',
-			type: 'nps',
-			title: 'How likely are you to recommend us?',
-			description: 'Your feedback helps us improve',
-			low_label: 'Not likely',
-			high_label: 'Very likely',
-			trigger: 'manual',
+			name: 'NPS Score',
+			slug: 'nps',
 			status: 'active',
+			trigger_type: 'manual',
+			pages: [
+				{
+					id: 'nps-page-1',
+					type: 'rating',
+					title: 'How likely are you to recommend us to a friend?',
+					description: '',
+					placeholder: '',
+					rating_config: { scale: 11, low_label: 'Very unlikely', high_label: 'Very likely', survey_type: 'nps' },
+					multiple_choice_config: null,
+					link_config: null,
+					after_this_page: { default: 'end_survey', conditions: [] },
+					required: true,
+				},
+			],
 		},
 		{
 			id: 'mock_csat_survey',
-			type: 'csat',
-			title: 'How satisfied are you?',
-			description: 'Rate your experience with our product',
-			trigger: 'manual',
+			name: 'CSAT Survey',
+			slug: 'csat',
 			status: 'active',
+			trigger_type: 'manual',
+			pages: [
+				{
+					id: 'csat-page-1',
+					type: 'rating',
+					title: 'How satisfied are you with our service?',
+					description: '',
+					placeholder: '',
+					rating_config: { scale: 5, low_label: 'Very dissatisfied', high_label: 'Very satisfied', survey_type: 'emoji' },
+					multiple_choice_config: null,
+					link_config: null,
+					after_this_page: { default: 'end_survey', conditions: [] },
+					required: true,
+				},
+			],
 		},
 		{
 			id: 'mock_ces_survey',
-			type: 'ces',
-			title: 'How easy was it?',
-			description: 'Rate the ease of completing your task',
-			low_label: 'Very difficult',
-			high_label: 'Very easy',
-			trigger: 'manual',
+			name: 'Customer Effort Score',
+			slug: 'ces',
+			status: 'active',
+			trigger_type: 'manual',
+			pages: [
+				{
+					id: 'ces-page-1',
+					type: 'rating',
+					title: 'How easy was it to use our product?',
+					description: '',
+					placeholder: '',
+					rating_config: { scale: 5, low_label: 'Very difficult', high_label: 'Very easy', survey_type: 'ces' },
+					multiple_choice_config: null,
+					link_config: null,
+					after_this_page: { default: 'end_survey', conditions: [] },
+					required: true,
+				},
+			],
+		},
+		{
+			id: 'mock_open_question_survey',
+			name: 'Open Question',
+			slug: 'open-question',
+			status: 'active',
+			trigger_type: 'manual',
+			pages: [
+				{
+					id: 'open-page-1',
+					type: 'text',
+					title: 'What could we do better?',
+					description: 'Is there anything we could do to make our product better for you?',
+					placeholder: 'Type your answer here',
+					rating_config: null,
+					multiple_choice_config: null,
+					link_config: null,
+					after_this_page: { default: 'end_survey', conditions: [] },
+					required: true,
+				},
+			],
+		},
+		{
+			id: 'mock_product_idea_poll_survey',
+			name: 'Product Idea Poll',
+			slug: 'product-idea-poll',
 			status: 'active',
+			trigger_type: 'manual',
+			pages: [
+				{
+					id: 'poll-page-1',
+					type: 'multiple_choice',
+					title: 'Which feature should we add next?',
+					description: 'Vote on the feature you would like to see next.',
+					placeholder: '',
+					rating_config: null,
+					multiple_choice_config: {
+						allow_multiple_selection: false,
+						survey_type: 'regular',
+						options: [
+							{ id: 'opt1', label: 'Better reporting' },
+							{ id: 'opt2', label: 'Mobile app' },
+							{ id: 'opt3', label: 'Integrations' },
+							{ id: 'opt4', label: 'AI features' },
+						],
+					},
+					link_config: null,
+					after_this_page: { default: 'end_survey', conditions: [] },
+					required: true,
+				},
+			],
+		},
+		{
+			id: 'mock_pmf_survey',
+			name: 'Product Market Fit (PMF)',
+			slug: 'pmf',
+			status: 'active',
+			trigger_type: 'manual',
+			pages: [
+				{
+					id: 'pmf-page-1',
+					type: 'multiple_choice',
+					title: 'How would you feel if you could no longer use our product?',
+					description: '',
+					placeholder: '',
+					rating_config: null,
+					multiple_choice_config: {
+						allow_multiple_selection: false,
+						survey_type: 'regular',
+						options: [
+							{ id: 'very_disappointed', label: 'Very disappointed' },
+							{ id: 'somewhat_disappointed', label: 'Somewhat disappointed' },
+							{ id: 'not_disappointed', label: 'Not disappointed' },
+						],
+					},
+					link_config: null,
+					after_this_page: { default: 'end_survey', conditions: [] },
+					required: true,
+				},
+			],
+		},
+		{
+			id: 'mock_user_interview_survey',
+			name: 'User Interview Request',
+			slug: 'user-interview',
+			status: 'active',
+			trigger_type: 'manual',
+			pages: [
+				{
+					id: 'interview-page-1',
+					type: 'link',
+					title: 'Would you like to hop on a quick demo?',
+					description: 'We would love to hear your thoughts and answer any questions you have.',
+					placeholder: '',
+					rating_config: null,
+					multiple_choice_config: null,
+					link_config: {
+						button_text: 'Book a demo',
+						link_text: '',
+						redirect_url: 'https://example.com',
+						open_in: 'new_tab',
+					},
+					after_this_page: { default: 'end_survey', conditions: [] },
+					required: true,
+				},
+			],
 		},
 	];
 
@@ -7368,6 +7509,8 @@
 					return this._renderMultipleChoicePage(page);
 				case 'text':
 					return this._renderTextPage(page);
+				case 'link':
+					return this._renderLinkPage(page);
 				default:
 					return this._renderTextPage(page);
 			}
@@ -7426,6 +7569,21 @@
 			`;
 			}
 
+			if (ratingType === 'ces') {
+				const cesLabels = ['Very Difficult', 'Difficult', 'Neutral', 'Easy', 'Very Easy'];
+				return `
+				<div class="feedback-survey-ces" data-page-id="${pageId}">
+					${cesLabels
+						.map((label, i) => {
+							const score = i + 1;
+							const selected = currentRating === score ? ' selected' : '';
+							return `<button class="feedback-survey-page-rating-btn feedback-survey-ces-btn${selected}" data-page-id="${pageId}" data-score="${score}">${label}</button>`;
+						})
+						.join('')}
+				</div>
+			`;
+			}
+
 			if (ratingType === 'emoji' && scale === 5) {
 				const emojis = [
 					'\uD83D\uDE1E',
@@ -7468,7 +7626,9 @@
 				page.multipleChoiceConfig || page.multiple_choice_config || {};
 			const options = Array.isArray(config.options) ? config.options : [];
 			const allowMultiple =
-				config.allow_multiple === true || config.multiple === true;
+				config.allow_multiple === true ||
+				config.multiple === true ||
+				config.allow_multiple_selection === true;
 			const pageAnswer = this.surveyState.pageAnswers[pageId] || {};
 			const selectedValues = Array.isArray(pageAnswer.values)
 				? pageAnswer.values
@@ -7495,10 +7655,36 @@
 			const pageId = page.id || `page_${this.surveyState.currentPageIndex}`;
 			const pageAnswer = this.surveyState.pageAnswers[pageId] || {};
 			const value = pageAnswer.text || '';
+			const placeholder = page.placeholder || 'Type your answer...';
 
 			return `
 			<div class="feedback-survey-text-page" data-page-id="${pageId}">
-				<textarea class="feedback-survey-page-textarea" data-page-id="${pageId}" placeholder="Type your answer...">${value}</textarea>
+				<textarea class="feedback-survey-page-textarea" data-page-id="${pageId}" placeholder="${placeholder}">${value}</textarea>
+			</div>
+		`;
+		}
+
+		_renderLinkPage(page) {
+			const pageId = page.id || `page_${this.surveyState.currentPageIndex}`;
+			const config = page.link_config || page.linkConfig || {};
+			const buttonText = config.button_text || config.buttonText || 'Click here';
+			const linkText = config.link_text || config.linkText || '';
+			const redirectUrl = config.redirect_url || config.redirectUrl || '#';
+			const openIn = config.open_in || config.openIn || 'new_tab';
+			const target = openIn === 'new_tab' ? '_blank' : '_self';
+			const pageAnswer = this.surveyState.pageAnswers[pageId] || {};
+			const clicked = pageAnswer.clicked === true;
+
+			return `
+			<div class="feedback-survey-link-page" data-page-id="${pageId}">
+				${linkText ? `<p class="feedback-survey-link-text">${linkText}</p>` : ''}
+				<a class="feedback-survey-link-btn${clicked ? ' selected' : ''}"
+				   href="${redirectUrl}"
+				   target="${target}"
+				   rel="noopener noreferrer"
+				   data-page-id="${pageId}">
+					${buttonText}
+				</a>
 			</div>
 		`;
 		}
@@ -7747,6 +7933,24 @@
 					});
 				}
 			}
+
+			if (page.type === 'link') {
+				this.surveyElement
+					.querySelectorAll('.feedback-survey-link-btn')
+					.forEach((btn) => {
+						btn.addEventListener('click', () => {
+							const pId = btn.dataset.pageId;
+							this._setPageAnswer(pId, { clicked: true });
+							btn.classList.add('selected');
+
+							const navigation = page.afterThisPage || page.after_this_page;
+							const goesTo = navigation ? navigation.default : null;
+							if (!goesTo || goesTo === 'end_survey') {
+								setTimeout(() => this._handleSubmit(), 400);
+							}
+						});
+					});
+			}
 		}
 
 		_selectNPS(score) {
@@ -7938,6 +8142,13 @@
 				}
 			}
 
+			if (page.type === 'link') {
+				if (page.required && !answer.clicked) {
+					this._showError('Please click the link to continue');
+					return false;
+				}
+			}
+
 			return true;
 		}
 
@@ -8667,6 +8878,7 @@
 					type: page.type || 'rating',
 					title: page.title || '',
 					description: page.description || '',
+					placeholder: page.placeholder || '',
 					required: page.required !== false,
 					position: page.position ?? index,
 					ratingConfig: page.ratingConfig || page.rating_config || null,