@explorer02/cfm-survey-sdk 0.1.3 → 0.1.5

package/templates/docs/01-sdk-core/01-fetch-survey.md

@@ -0,0 +1,68 @@
+# Fetch Survey — `useFetchSurvey`
+
+> **Source**: `packages/sdk/src/fetchSurvey/useFetchSurvey.ts`
+> **Called by**: `useSurveySDK()` internally — the client never calls this directly.
+
+## What It Does
+
+1. Builds the API URL from the client's `instanceId` (JWT token)
+2. Makes a `GET` request to the Sprinklr CFM API endpoint
+3. Caches the raw response using `@tanstack/react-query` (singleton QueryClient — no provider needed)
+4. Re-maps the cached response whenever the target language changes (client-side, no re-fetch)
+
+## API Endpoint
+
+```
+https://custom-p0.feedbook.me/api/feedback/survey/cfm?instanceId={JWT_TOKEN}
+```
+
+The URL is constructed by `buildSurveyUrl()` in `fetchSurvey/utils/url.ts`.
+
+## Instance ID
+
+The `instanceId` is a **JWT token** string that encodes:
+- `surveyId` — Which survey to load
+- `distributionEntityId` — Which distribution channel
+- `surveyLanguage` — Default language (e.g. `'de'`)
+- `partnerId` — Tenant identifier
+
+**⚠️ CRITICAL**: The instanceId comes from the **client's chat prompt**. The agent must ask the client for it before building the survey. Without it, `useFetchSurvey` returns `null` and the survey cannot load.
+
+## Return Shape
+
+```typescript
+{
+  survey: Survey | null,       // Fully mapped survey object (see 02-survey-mapper.md)
+  session: SurveySession | null, // { instanceId, language } — passed to submit hook
+  fetching: boolean,           // True while network request is in flight
+  fetchError: Error | null,    // Network/API error
+}
+```
+
+## Caching Behaviour
+
+- Keyed by `['survey', url]` — fetched **once** per instanceId
+- Language changes do NOT re-fetch — they re-map the cached raw response via `useMemo`
+- Uses `cache: 'force-cache'` on the fetch request for browser-level HTTP caching
+
+## QueryClient
+
+The SDK creates its own internal singleton `QueryClient` in `src/queryClient.ts`.
+The client app does **NOT** need to wrap anything in `<QueryClientProvider>`.
+
+## Logging & Telemetry
+
+The fetch lifecycle emits structured logs (when `debug: true`):
+- `logFetchStart(url)` — before the request
+- `logFetchPerfSuccess(durationMs, status, url, payloadSize)` — on success
+- `logFetchPerfFailure(durationMs, status, url)` — on failure
+- `trackFetchLatency(...)` — performance telemetry
+
+## Error Handling
+
+| Scenario | Behaviour |
+|----------|-----------|
+| Network offline | `fetchError` populated, `survey` is `null` |
+| HTTP 4xx/5xx | `fetchError` populated with status message |
+| Invalid instanceId | API returns empty/malformed → `survey` maps to `null` |
+| Successful but empty | `survey` is `null`, no error |

package/templates/docs/01-sdk-core/02-survey-mapper.md

@@ -0,0 +1,85 @@
+# Survey Mapper — `mapSurvey`
+
+> **Source**: `packages/sdk/src/fetchSurvey/utils/mappers/surveyMapper.ts`
+> **Called by**: `useFetchSurvey()` inside `useMemo` — re-runs when language changes.
+
+## What It Does
+
+Transforms the raw API response (`ApiResponse`) into a clean, typed `Survey` object:
+
+```
+ApiResponse (raw network JSON)
+    │
+    ├── extractQuestions()      → Flat list of ApiQuestion[]
+    ├── resolveSurveyLanguage() → Determine active language code
+    ├── extractSurveyLanguages()→ Build SurveyLanguage[] for language switcher
+    └── mapSurveyPages()        → Pages → Questions → per-type mappers
+            │
+            └── mapQuestion() per question (see 03-question-mappers.md)
+```
+
+## Output: `Survey` Type
+
+```typescript
+type Survey = {
+  id: string;                    // Survey identifier
+  language: string;              // Active language code (e.g. 'en', 'de')
+  languages: SurveyLanguage[];   // All available languages for the switcher
+  pages: SurveyPageData[];       // Ordered list of pages
+};
+
+type SurveyPageData = {
+  id: string;                    // Page identifier
+  title?: string;                // Optional page heading
+  questions: SurveyQuestion[];   // Questions on this page
+};
+
+type SurveyLanguage = {
+  code: string;                  // BCP-47 code (e.g. 'de')
+  name: string;                  // Display name (e.g. 'Deutsch')
+};
+```
+
+## Key Functions
+
+### `extractQuestions(api)`
+Traverses `api.cfmSurveyDTO.surveyPages[].questionHolders[].question` to produce a flat array of raw API questions.
+
+### `resolveSurveyLanguage(api, language?)`
+Priority: `language` parameter → `api.surveyLanguage` → `api.cfmSurveyDTO.baseLanguage` → `'en'`
+
+### `extractSession(api)`
+Returns `{ instanceId, language }` or `null` if no valid instanceId exists. This session object is passed to the submit hook.
+
+### `mapSurveyPages(api, language, placeholders)`
+Iterates over `api.cfmSurveyDTO.surveyPages`, calling `mapQuestion()` for each question within each page's `questionHolders`. Returns `SurveyPageData[]`.
+
+## API Response Structure (Simplified)
+
+```typescript
+type ApiResponse = {
+  instanceId: string;
+  surveyLanguage: string;
+  cfmSurveyDTO: {
+    id: string;
+    baseLanguage: string;
+    surveyPages: Array<{
+      id: string;
+      pageTitle?: string;
+      questionHolders: Array<{
+        question: ApiQuestion;
+      }>;
+    }>;
+  };
+};
+```
+
+## Language Re-mapping
+
+When the user switches language via the `LanguageSelector`:
+1. `selectedLanguage` state changes in `SurveyPage.tsx`
+2. This flows into `useSurveySDK({ options: { language: selectedLanguage } })`
+3. `useFetchSurvey` does **NOT re-fetch** — the raw `ApiResponse` is cached
+4. `useMemo` re-runs `mapSurvey(apiResponse, newLanguage, placeholders)`
+5. Each question's text, options, and labels are resolved from `translations[language]`
+6. The entire UI re-renders with translated content

package/templates/docs/01-sdk-core/03-question-mappers.md

@@ -0,0 +1,114 @@
+# Question Mappers — `mapQuestion`
+
+> **Source**: `packages/sdk/src/fetchSurvey/utils/mappers/questionMappers/index.ts`
+> **Called by**: `mapSurveyPages()` for each question in each page.
+
+## What It Does
+
+Takes a raw `ApiQuestion` and produces a fully typed `SurveyQuestion` variant. This is the core routing logic that determines what question type the client component will render.
+
+## Dispatch Pipeline
+
+```
+ApiQuestion
+    │
+    ├── resolveBase(raw, configs, language, placeholders)
+    │   → { id, text, description, required, requiredErrorMessage, containerMedia* }
+    │
+    ├── normalizeType(raw.answerType)
+    │   → 'rating' | 'text' | 'matrix' | 'rating_matrix' | 'slider_matrix'
+    │     | 'text_and_media' | 'file_upload' | 'radio' (default)
+    │
+    └── switch(type) → per-type mapper
+        ├── 'rating'         → mapRatingQuestion()   [handles NPS, CSAT, Slider, RatingScale]
+        ├── 'text'           → mapTextQuestion()
+        ├── 'matrix'         → mapMatrixQuestion()   [handles CFM, CSAT, RATING matrix]
+        ├── 'rating_matrix'  → mapMatrixQuestion()   [same handler, different subType]
+        ├── 'slider_matrix'  → mapSliderMatrixQuestion()
+        ├── 'text_and_media' → mapTextAndMediaQuestion()
+        ├── 'file_upload'    → mapFileUploadQuestion()
+        └── default          → mapRadioQuestion()    [MCQ and any unrecognised type]
+```
+
+## `normalizeType(answerType)` — Type Resolution
+
+| API `answerType` | Normalized Type | Notes |
+|-----------------|----------------|-------|
+| `'SCALE'` | `'rating'` | Further sub-typed inside ratingMapper |
+| `'RATING'` | `'rating'` | Legacy alias |
+| `'RATING_MATRIX'` | `'rating_matrix'` | Grid with NPS-style columns |
+| `'TEXTFIELD'` | `'text'` | Short or long text input |
+| `'MCQ'` | `'radio'` | Multiple choice (single select) |
+| `'CFM_MATRIX'` | `'matrix'` | Likert-style grid |
+| `'CSAT_MATRIX'` | `'matrix'` | Satisfaction grid with emoji/star |
+| `'SLIDER_MATRIX'` | `'slider_matrix'` | Grid of range sliders |
+| `'TEXT_AND_MEDIA'` | `'text_and_media'` | Display-only media card |
+| `'FILE_UPLOAD'` | `'file_upload'` | File attachment question |
+| Any other | `'radio'` | Safe fallback |
+
+## `resolveBase()` — Shared Fields
+
+Every question variant inherits these base fields:
+
+```typescript
+type QuestionBase = {
+  id: string;                      // ⚠️ MUST be used as DOM element id
+  text: string;                    // May contain HTML — use dangerouslySetInnerHTML
+  description?: string;            // Supplementary instruction text (HTML)
+  required?: boolean;              // Whether answer is mandatory
+  requiredErrorMessage?: string;   // Custom validation error text
+  questionNumber?: number;         // 1-indexed ordinal position
+  containerMediaUrl?: string;      // Image/video shown alongside question
+  containerMediaMimeType?: string; // MIME type for container media
+  containerMediaAlignment?: string;// Layout position of container media
+  containerMediaSize?: number;     // Width percentage of container media
+};
+```
+
+### Text Resolution Priority
+```
+language translation (richText) → language translation (plainText)
+  → default richText → default plainText → ''
+```
+
+### Placeholder Replacement
+The `resolveBase` function replaces `{{TOKEN}}` patterns in question text and description:
+```typescript
+text.replace(/\{\{(\w+)\}\}/g, (match, key) =>
+  placeholders[key] !== undefined ? placeholders[key] : match
+);
+```
+
+## Rating Mapper Sub-Dispatch
+
+The `mapRatingQuestion()` handler further sub-types based on `questionConfigs`:
+
+```
+SCALE answerType
+    │
+    ├── SCALE_TYPE=CSAT (or ≤5 options) → type: 'csat'
+    ├── SCALE_TYPE=STAR/EMOJI/FIVE_POINT → type: 'rating_scale'
+    ├── INPUT_TYPE=SLIDER → type: 'slider'
+    └── default (NPS/TEN_POINT) → type: 'rating'
+```
+
+This means the client component's `Question.tsx` needs to handle **all these refined types**, not just the raw `'rating'` type.
+
+## Final Output: `SurveyQuestion` Union
+
+```typescript
+type SurveyQuestion =
+  | RatingQuestion        // type: 'rating'
+  | RadioQuestion         // type: 'radio'
+  | TextQuestion          // type: 'text'
+  | MatrixQuestion        // type: 'matrix'
+  | RatingMatrixQuestion  // type: 'rating_matrix'
+  | SliderMatrixQuestion  // type: 'slider_matrix'
+  | TextAndMediaQuestion  // type: 'text_and_media'
+  | CsatQuestion          // type: 'csat'
+  | SliderQuestion        // type: 'slider'
+  | RatingScaleQuestion   // type: 'rating_scale'
+  | FileUploadQuestion;   // type: 'file_upload'
+```
+
+Each type is documented in detail in `02-question-types/`.

package/templates/docs/01-sdk-core/04-pagination.md

@@ -0,0 +1,72 @@
+# Pagination — `useSurveyPagination`
+
+> **Source**: `packages/sdk/src/surveyPagination/useSurveyPagination.ts`
+> **Called by**: `useSurveySDK()` internally.
+
+## What It Does
+
+Manages the multi-page survey state: current page index, user answers, validation errors, page navigation, and wires into submission and progress tracking.
+
+## State Shape
+
+```typescript
+{
+  currentPageIndex: number,                    // Zero-based active page
+  values: Record<string, AnswerValue>,         // All answers keyed by question ID
+  validationErrors: Record<string, string>,    // Error messages keyed by question ID
+  currentQuestions: SurveyQuestion[],          // Questions on the active page
+  progressPercentage: number,                  // 0–100 completion percentage
+}
+```
+
+## Navigation Actions
+
+### `onNext()` (dispatched by `onAction({ type: 'NEXT' })`)
+1. Validates all questions on the current page
+2. If validation fails → populates `validationErrors` → scrolls to first error
+3. If validation passes → clears errors → increments `currentPageIndex`
+4. If already on the last page → auto-redirects to `onSubmit()`
+
+### `onBack()` (dispatched by `onAction({ type: 'PREVIOUS' })`)
+1. Decrements `currentPageIndex` (minimum 0)
+2. Scrolls to the top of the new page
+3. Logs backtrack analytics
+
+### `onChange(questionId, value)` (dispatched by `onAction({ type: 'CHANGE', payload })`)
+1. Updates `values[questionId] = value`
+2. If the question had a validation error, clears it immediately
+
+### `onSubmit()` (dispatched by `onAction({ type: 'SUBMIT' })` or auto-triggered)
+1. Validates ALL pages (not just current)
+2. If any page has errors → navigates to the error page → scrolls to first error
+3. If all valid → calls `submit(values)` → sends response to server
+
+## Progress Tracking
+
+`useSurveyProgress` computes `progressPercentage`:
+- Counts total answerable questions across ALL pages (excludes `text_and_media`)
+- Counts questions that have a non-empty value in `values`
+- Formula: `(answered / total) * 100`
+
+## Internal Refs (Analytics)
+
+The hook maintains a `useRef` for analytics data that persists across renders:
+- `pageStartTime` — timestamp when current page was entered
+- `sessionStartTime` — timestamp when survey was first loaded
+- `maxVisitedPageIndex` — furthest page the user has reached
+- `validationErrorsCount` — total validation failures during the session
+- `backtrackCount` — number of times user navigated backwards
+
+These are used for telemetry and do NOT affect the UI.
+
+## Auto-Submit on Last Page
+
+When `onAction({ type: 'NEXT' })` is dispatched on the last page, the SDK's `useSurveySDK` dispatcher automatically converts it to `{ type: 'SUBMIT' }`:
+
+```typescript
+if (action.type === 'NEXT' && currentPageIndex === survey.pages.length - 1) {
+  action = { type: 'SUBMIT' };
+}
+```
+
+This means the client's "Next" button on the last page automatically becomes "Submit" in behaviour.

package/templates/docs/01-sdk-core/05-validation.md

@@ -0,0 +1,66 @@
+# Validation — `validateQuestions` & `validateAllPages`
+
+> **Source**: `packages/sdk/src/surveyPagination/utils/validation.ts`
+> **Called by**: `useOnNext()` and `useOnSubmit()` internally.
+
+## What It Does
+
+Validates required questions before allowing page navigation or survey submission. Populates `state.validationErrors` with per-question error messages.
+
+## Validation Rules
+
+### Standard Questions (rating, radio, text, csat, rating_scale, slider)
+- **Required check**: `value !== undefined && value !== ''`
+- `null` is treated as a **valid** answer (represents the N/A option)
+
+### Matrix Questions (matrix, rating_matrix, slider_matrix)
+- Every row must have a value: `question.rows.every(row => answerMap[row.id] !== undefined && answerMap[row.id] !== '')`
+- `null` per row is valid (N/A option)
+
+### Display-Only Questions (text_and_media)
+- **Always skipped** — `isDisplayOnly()` returns `true`
+- Never counted in validation or progress
+
+## Error Messages
+
+| Source | Priority |
+|--------|----------|
+| `question.requiredErrorMessage` (from API) | **Highest** — custom per-question message |
+| Language-aware default | Fallback |
+
+Default messages:
+- German (`de`): `"Beantworten Sie bitte diese Frage bevor Sie fortfahren."`
+- All other: `"Please answer this question before you proceed."`
+
+## Scroll-to-Error
+
+When validation fails, the SDK:
+1. Identifies the first question with an error
+2. Calls `document.getElementById(questionId)` to find the DOM element
+3. Calls `.scrollIntoView({ behavior: 'smooth', block: 'center' })` to scroll to it
+
+**⚠️ CRITICAL**: This is why every question wrapper element MUST have `id={question.id}`.
+
+## `validateQuestions(questions, values, language)`
+
+Validates a single page's questions. Returns `Record<string, string>` of errors (empty if all valid).
+
+## `validateAllPages(pages, values, language)`
+
+Validates ALL pages at once (used before submission). Returns:
+```typescript
+{
+  errors: Record<string, string>,  // All errors across all pages
+  errorPageIndex: number,          // First page with errors
+  firstErrorId: string,            // First question ID with error
+} | null                           // null = all valid
+```
+
+When this returns non-null, the SDK:
+1. Navigates to `errorPageIndex`
+2. Sets all errors into `validationErrors` state
+3. Scrolls to `firstErrorId`
+
+## `isQuestionAnswered(question, values)`
+
+Exported utility that checks if a single question has been answered. Used by both validation and progress tracking.

package/templates/docs/01-sdk-core/06-submit-survey.md

@@ -0,0 +1,90 @@
+# Submit Survey — `useSubmitResponse` & `buildSubmitRequestBody`
+
+> **Sources**:
+> - `packages/sdk/src/submitSurvey/useSubmitResponse.ts`
+> - `packages/sdk/src/submitSurvey/utils/formatters.ts`
+
+## What It Does
+
+Formats user answers into the Sprinklr CFM API payload structure and sends them via POST.
+
+## Submission Endpoint
+
+```
+POST https://custom-p0.feedbook.me/api/feedback/survey/cfm/response
+```
+
+## Payload Format — `SubmitRequestBody`
+
+```typescript
+{
+  questionToAnswers: Record<string, string[]>,     // Standard + matrix row answers
+  quesIdVsAttachmentDetails: Record<string, any[]>, // File upload attachments
+  optionLevelAnswers: Record<string, string[]>,     // (reserved)
+  conjointTasks: unknown[],                         // (reserved — always [])
+}
+```
+
+## Per-Type Serialization
+
+### Standard Questions (rating, radio, text, csat, rating_scale, slider)
+```
+questionToAnswers[questionId] = [String(value)]
+```
+
+### Matrix Questions (matrix, rating_matrix, slider_matrix)
+Each row becomes a separate entry with a combined key:
+```
+questionToAnswers[`${questionId}_${rowId}`] = [String(rowValue)]
+```
+
+### File Upload
+```
+quesIdVsAttachmentDetails[questionId] = [
+  { id: "...", name: "file.pdf", mediaUrl: "https://..." },
+  ...
+]
+```
+
+### Text and Media (display-only)
+Completely skipped — no data submitted.
+
+## Answer Value Types
+
+```typescript
+type AnswerValue = string | number | null | MatrixAnswerMap | any[];
+
+type MatrixAnswerMap = Record<string, string | number | null | Array<string | number | null>>;
+```
+
+| Question Type | Answer Shape | Example |
+|--------------|-------------|---------|
+| `rating` | `number` | `7` |
+| `radio` | `string \| number` | `"option_1"` |
+| `text` | `string` | `"Great service"` |
+| `csat` | `number \| null` | `4` or `null` (N/A) |
+| `rating_scale` | `number` | `3` |
+| `slider` | `number` | `65` |
+| `matrix` | `MatrixAnswerMap` | `{ "row1": "col2", "row2": null }` |
+| `slider_matrix` | `MatrixAnswerMap` | `{ "row1": 75, "row2": 30 }` |
+| `file_upload` | `UploadedFile[]` | `[{ id, name, mediaUrl }]` |
+| `text_and_media` | (none) | Not submitted |
+
+## Submit Result
+
+```typescript
+type SubmitResult = {
+  success: boolean;
+  responseId: string;   // Generated database ID for the response
+};
+```
+
+Accessible via `submitSurveyResults.data` in the component.
+
+## Error Handling
+
+| Scenario | Behaviour |
+|----------|-----------|
+| Network failure | `submitSurveyResults.error` populated |
+| Server rejection | `submitSurveyResults.error` populated with status |
+| During submission | `submitSurveyResults.isLoading = true` — disable submit button |

package/templates/docs/01-sdk-core/07-language-handling.md

@@ -0,0 +1,111 @@
+# Language Handling — Translations & Placeholders
+
+> **Source**: `packages/sdk/src/fetchSurvey/utils/extractSurveyLanguages.ts`
+
+## How Multi-Language Works
+
+1. The raw API response contains `translations` objects on each question and answer detail
+2. `extractSurveyLanguages()` scans all questions to discover available language codes
+3. `mapSurvey()` resolves text fields using the active language's translations
+4. Language switching is **client-side only** — no API re-fetch
+
+## Language Discovery
+
+The SDK traverses all questions in the survey and collects unique language codes from `question.translations` keys:
+
+```typescript
+// Pseudocode
+languagesSet.add(baseLanguage); // e.g. 'de'
+for each question:
+  for each key in question.translations:
+    languagesSet.add(key);  // e.g. 'en', 'fr'
+```
+
+## Display Names
+
+Built-in language code → display name mapping:
+
+| Code | Display Name |
+|------|-------------|
+| `en` | English |
+| `de` | Deutsch |
+| `hi` | Hindi |
+| `es` | Español |
+| `fr` | Français |
+| `it` | Italiano |
+| `ja` | 日本語 |
+| `ko` | 한국어 |
+| `zh` | 中文 |
+| `bn` | Bengali |
+| `gu` | Gujarati |
+| `mr` | Marathi |
+| `pa` | Punjabi |
+| `ta` | Tamil |
+| `te` | Telugu |
+| `ur` | Urdu |
+
+Unknown codes fall back to `code.toUpperCase()`.
+
+## Translation Resolution Priority
+
+For question text:
+```
+translations[language].questionRichText
+  → translations[language].questionText
+  → raw.questionRichText
+  → raw.questionText
+  → ''
+```
+
+For answer option labels:
+```
+translations[language].answerText → raw.answerText → ''
+```
+
+For validation error messages:
+```
+config.translations[language].value[0] → config.value[0] → default message
+```
+
+## Placeholders
+
+Tokens like `{{FIRST_NAME}}` in question text are replaced at map time:
+
+```typescript
+const SURVEY_PLACEHOLDERS = {
+  FIRST_NAME: 'Customer',
+  LAST_NAME: 'Smith',
+  EMAIL_ADDRESS: 'customer@example.com',
+};
+```
+
+**⚠️ CRITICAL**: Define `SURVEY_PLACEHOLDERS` as a **constant outside the component** to prevent infinite re-render loops:
+
+```tsx
+// ✅ CORRECT — stable reference
+const SURVEY_PLACEHOLDERS = { FIRST_NAME: 'John' };
+export default function SurveyPage() { ... }
+
+// ❌ WRONG — new object every render → infinite re-fetch
+export default function SurveyPage() {
+  useSurveySDK({ options: { placeholders: { FIRST_NAME: 'John' } } });
+}
+```
+
+## Language Switching in UI
+
+```tsx
+const [selectedLanguage, setSelectedLanguage] = useState<string | undefined>("");
+
+// Pass to SDK
+const { ... } = useSurveySDK({ options: { language: selectedLanguage } });
+
+// Render selector
+<LanguageSelector
+  languages={survey.languages}
+  selectedLanguage={survey.language}
+  onChange={setSelectedLanguage}
+/>
+```
+
+When `setSelectedLanguage` fires, the SDK re-maps the cached survey data to the new language — no network request.