@explorer02/cfm-survey-sdk 0.2.1 → 0.2.3

package/templates/AGENT.md

@@ -3,9 +3,9 @@ You are an AI coding agent tasked with building a survey UI using the CFM Survey
 ## Start Here
 
 **Monorepo:** read `packages/sdk/templates/docs/index.md`  
-**Installed package:** read `node_modules/@explorer02/cfm-survey-sdk/docs/index.md`
+**Installed package:** read `node_modules/@explorer02/cfm-survey-sdk/templates/docs/index.md`
 
-Also read `MANIFEST.json` in the same `docs/` folder for machine-readable phase and question-type routing.
+Also read `MANIFEST.json` in the same `templates/docs/` folder for machine-readable phase and question-type routing.
 
 ## Package Name
 
@@ -20,14 +20,24 @@ Import from whatever appears in `package.json`:
 | 0 | Detect framework; extract branding from client prompt |
 | 1 | Scaffold React app — `00-integration/setup.md` |
 | 2 | Ask client for instanceId JWT |
-| 3 | Read `useSurveySDK.md` — hook contract |
-| 4 | Read all `01-components/`; inventory survey types; read `03-ui-specs/` per type; copy `templates/Question.tsx` + `implementation_plan.md` |
-| 5 | Build UI — create all scale files from `component-checklist.md`; no stub placeholders |
-| 6 | Verify build checklist |
-| 7 | Deploy on client confirmation |
+| 3 | Read `client-integration-guide.md` + `question-type-sdk-matrix.md` + hook/logic/lifecycle/analytics docs — full SDK contract |
+| 4 | Fetch survey; inventory types; read MANIFEST-driven docs per type; copy `templates/Question.tsx` + scale templates + `implementation_plan.md` |
+| 5 | Build UI — copy templates from `docs/templates/`; read ui-spec Implementation Recipes; dispatch on **11** flat `QUESTION_TYPE` literals |
+| 6 | Run `templates/verify-agent-build.sh` |
+| 7 | On confirmation: **AWS prompt** → `aws-deploy.md`; **Vercel prompt** → `npx cfm-sdk deploy` |
 
 **Do NOT** run `cfm-sdk init`, read `survey-config.json`, or use any setup wizard.
 
-**Do NOT** render `"not yet implemented"` or default fallback stubs in `Question.tsx`. Copy `docs/templates/Question.tsx` and create all required scale components.
+**Do NOT** render `"not yet implemented"` or default fallback stubs in `Question.tsx`. Copy `templates/docs/templates/Question.tsx` and create all required scale components.
+
+**Copy scale templates from `docs/templates/`** before implementing from ui-spec recipes: `RankOrderScale.tsx`, `MatrixDropdown.tsx`, `CustomSliderTrack.tsx`, `surveyUiIcons.tsx`, `heatmapCoords.ts`.
+
+**Do NOT** route matrix questions by `subType` — use flat types: `CFM_MATRIX`, `CSAT_MATRIX`, `RATING_MATRIX`, `SLIDER_MATRIX`.
+
+**Read `question-type-sdk-matrix.md` before building any scale component** — it defines answer shapes, visibility helpers, and performance expectations for all 11 types.
+
+**FILE_UPLOAD:** wire presigned upload per `00-integration/file-upload-aws.md` — raw `File[]` does not submit.
+
+**Monorepo:** run `npm run build` in `packages/sdk` before starting the client dev server.
 
 Follow the master index strictly. Do not guess SDK internals. Do not import from `/src/` paths.

package/templates/docs/00-integration/analytics-events-catalog.md

@@ -0,0 +1,54 @@
+# Analytics Events Catalog
+
+> Consolidated SDK telemetry and client-wired lifecycle events. Most events log to console as `[SDK:ANALYTICS]` — **no client code required** unless noted.
+
+See also: [`survey-lifecycle-analytics.md`](survey-lifecycle-analytics.md) · [`client-integration-guide.md`](client-integration-guide.md) § Debug logging
+
+---
+
+## Client must wire
+
+| Event / action | How | When |
+|----------------|-----|------|
+| Mark as started | `onAction({ type: 'SCROLL' })` once on first window scroll | First content engagement |
+| Question viewed | `onAction({ type: 'RECORD_QUESTION_VIEW', payload: { questionId } })` via IntersectionObserver on `#question.id` | Question 50% visible |
+| Partial save feedback | Monitor `partialSaveResults.isLoading` / `.error` | When `savePartialResponse: true` |
+
+First `CHANGE` also triggers mark-as-started (SDK) — no extra client call.
+
+---
+
+## SDK-emitted (always — no `debug` flag required)
+
+| Event | When | Metadata highlights |
+|-------|------|---------------------|
+| `fetch_survey_latency` | Survey GET completes | durationMs, status, payloadSize (UTF-8 KB) |
+| `fetch_survey_error` | Survey GET fails | status, url, message |
+| `submit_survey_latency` | Submit POST completes | durationMs, status |
+| `submit_survey_error` | Submit fails | status, message |
+| `page_time_spent` | Leaving a content page | pageIndex, durationMs |
+| `optional_question_skipped` | Optional question left blank on forward nav | questionId, pageIndex |
+| `backtrack_revisited` | User returns to earlier page and changes answers | fromPage, toPage, changedAnswers |
+| `question_viewed` | After RECORD_QUESTION_VIEW deduped | questionId |
+| `display_logic_matched` | Display condition newly true | questionId, logic details |
+| `answer_logic_matched` | Answer-logic sub-entity newly visible | entity scope |
+| `question_variant_matched` | Variant text switches | variant id |
+| `end_page_logic_matched` | Resolved end page changes | endPageId |
+| `skip_logic_triggered` | Skip logic newly activates | skip target |
+
+---
+
+## Post-submit rollups
+
+| Event | When | Contents |
+|-------|------|----------|
+| `survey_session_summary` | Successful submit | `completed`, `maxVisitedPageIndex`, `totalDurationMs`, question counts (total/answered/skipped), `validationErrorsCount`, `backtrackCount`, `validationHistory` |
+| `logic_session_summary` | Successful submit | Per-logic-kind counts, viewed vs on-path-not-viewed, final end page, `logicEventTimeline` audit (console.table) |
+
+Enable `debug: true` in hook options for additional `[SDK:INFO]` transition logs (display/answer/variant/end/skip matches on answer change).
+
+---
+
+## Validation error tracking
+
+SDK increments validation error counts and records per-page error history in session summary. Client displays `state.validationErrors[questionId]` banners and uses `id={question.id}` for scroll-to-error.

package/templates/docs/00-integration/answer-logic-and-navigation.md

@@ -0,0 +1,50 @@
+# Answer Logic and Navigation
+
+> Integrator-facing behavior contract. Answer logic evaluation is handled inside the SDK — use exported visibility helpers; do not import internal `surveyLogic` paths directly.
+
+## Distinction from display logic
+
+Skip logic, display logic, and answer logic share the **same condition tree** and **same evaluator** (`evaluateCondition`). They differ by **what** the condition gates:
+
+| Kind | API attachment | SDK field | When true |
+|------|----------------|-----------|-----------|
+| `SKIP` | Question `controlConfig.skipLogics` | `question.skipLogics` | Navigate to skip target or end of survey |
+| `DISPLAY` | Question `controlConfig.displayLogic` | `question.displayLogic` | Show the whole question (dynamic or page-level) |
+| `ANSWER` | Sub-entity `controlConfig.displayLogic` | `answerLogic` on options / rows / columns | Show that option, statement row, or scale column |
+
+The API uses `displayLogic` on sub-entities (MCQ `answerDetails`, matrix `childSurveyQuestions`, scale `answerDetails` / `matrixColumnQuestions`). The SDK maps these to `answerLogic` to avoid confusion with question-level display logic.
+
+## Supported question types
+
+| Type | Answer logic on | Not supported |
+|------|-----------------|---------------|
+| MCQ | Each option | — |
+| SLIDER_MATRIX | Each statement row | Scale columns |
+| CSAT_MATRIX | Each statement row + each scale column | — |
+| RATING_MATRIX | Each statement row only | Scale columns |
+| CFM_MATRIX | Each statement row + each scale column | — |
+| RANK_ORDER | Each option | — |
+| NPS_SCALE, TEXTFIELD, FILE_UPLOAD, TEXT_AND_MEDIA | — | No answer logic |
+
+## Page breaks
+
+Adding answer logic in the survey builder creates a **page break before that question** (backend page structure). The SDK does not split pages at runtime; it filters visible items within the current page.
+
+If **every** answer item is hidden (all options, all rows, or all scale columns), the question is treated as not answerable and may disappear from `state.currentQuestions` (same pattern as display logic empty pages).
+
+## Client responsibilities
+
+1. Use `state.currentQuestions` from `useSurveySDK` — question-level display logic is already applied.
+2. **MCQ:** Filter options with `getVisibleMcqOptionsForAnswers(question, answers, allQuestions, customFieldValues?)`.
+3. **Rank order:** Filter options with `getVisibleRankOrderOptionsForAnswers(question, answers, allQuestions, customFieldValues?)`.
+4. **Matrix (CSAT, CFM, RATING, SLIDER):** Filter rows and (for CSAT/CFM) columns with `getVisibleMatrixItemsForAnswers(question, answers, allQuestions, customFieldValues?)`.
+5. Pass the same `customFieldValues` map used in `useSurveySDK` options when logic rules reference `CUSTOM_FIELD` entities — see [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md).
+6. Wire `onAction({ type: 'CHANGE' })` so answer logic re-evaluates when prior answers change.
+
+## Progress and validation
+
+- Progress and validation count only **visible** options, statement rows, and scale columns.
+- Hidden selections are stripped automatically on answer change via SDK sanitization.
+- Required questions with zero visible options are not blocked (treated as answered).
+
+See also: [`display-logic-and-navigation.md`](display-logic-and-navigation.md), [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md), [`progress.md`](progress.md).

package/templates/docs/00-integration/aws-deploy.md

@@ -0,0 +1,281 @@
+# AWS Deploy (EC2 Middle API → S3 → CloudFront)
+
+> Deploy a **static** survey UI to Sprinklr AWS using the hosted EC2 deploy API.
+> **Do not** embed AWS credentials in client code — the API uses IAM roles on EC2 to presign S3 URLs.
+
+Use this doc when the client prompt mentions **AWS**, **CloudFront**, **S3**, **EC2**, or **Sprinklr hosting**.
+For Vercel deploy, use `npx cfm-sdk deploy` instead (see `index.md` Phase 7).
+
+---
+
+## Architecture — Three-Channel Flow
+
+```mermaid
+sequenceDiagram
+  participant Dev as Agent_DevMachine
+  participant API as EC2_Deploy_API
+  participant S3 as Hosting_Bucket
+  participant CF as CloudFront
+
+  Dev->>Dev: yarn build or npm run build
+  Dev->>API: POST /deploy/start + JWT + file manifest
+  API-->>Dev: deployId + presigned PUT URLs
+  loop each file in out/
+    Dev->>S3: PUT file direct
+  end
+  Dev->>API: POST /deploy/complete
+  API->>S3: HeadObject index.html
+  API->>CF: CreateInvalidation
+  API-->>Dev: public HTTPS URL
+```
+
+| Channel | Direction | Action |
+|---------|-----------|--------|
+| 1 Control | Dev → EC2 API | `POST /deploy/start` with JWT + file manifest |
+| 2 Data | Dev → S3 direct | `PUT` each static file to presigned URLs |
+| 3 Finalize | Dev → EC2 API | `POST /deploy/complete` → CloudFront URL |
+
+S3 path shape: `sites/{surveyId}/{deployId}/` — extracted from JWT at deploy time.
+
+---
+
+## Prerequisites (verify before deploy)
+
+1. **Phase 6 passed** — `npm run build` / `yarn build` exits 0
+2. **JWT alignment** — deploy JWT **must equal** `SURVEY_INSTANCE_ID` in `SurveyPage.tsx`
+3. **Static output exists** — Next.js: `out/index.html`; Vite: `dist/index.html`
+4. **File count ≤ 500** (API limit)
+
+### Environment variables (dev machine)
+
+```bash
+export CFM_INSTANCE_ID="<same JWT as SurveyPage SURVEY_INSTANCE_ID>"
+export CFM_DEPLOY_API_BASE="http://43.204.26.213:3000"
+export OUT_DIR="<absolute path to static output folder>"
+# Next.js example:
+# export OUT_DIR="/path/to/project/out"
+# Vite example:
+# export OUT_DIR="/path/to/project/dist"
+```
+
+### Health check
+
+```bash
+curl -s "$CFM_DEPLOY_API_BASE/health"
+# Expected: {"ok":true,"service":"sprinklr-deploy-api"}
+```
+
+---
+
+## Build Config (apply during Phase 5 BUILD)
+
+### Next.js — static export (required for AWS)
+
+See also [`setup.md#nextjs-aws-static-export`](setup.md#nextjs-aws-static-export).
+
+**`next.config.js`:**
+
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  transpilePackages: ['@explorer02/cfm-survey-sdk'], // or '@repo/sdk'
+  output: 'export',
+  assetPrefix: './', // required for nested CloudFront path
+  images: { unoptimized: true },
+};
+module.exports = nextConfig;
+```
+
+**`package.json` build script** — copy RSC payload for `index.html` URLs:
+
+```json
+"build": "next build && cp out/index.txt out/index.html.txt"
+```
+
+| Setting | Why |
+|---------|-----|
+| `output: 'export'` | Produces uploadable `out/` folder (no Node server) |
+| `assetPrefix: './'` | Assets resolve under `/sites/{surveyId}/{deployId}/`, not CloudFront root |
+| `images.unoptimized` | Image optimization needs a server; static export does not |
+| `index.html.txt` copy | Fixes 403 on `index.html.txt?_rsc` when page URL ends with `index.html` |
+
+### Vite
+
+Set `OUT_DIR` to `dist/`. Ensure asset paths in built HTML are **relative** (no leading `/`). See Vite `base: './'` if needed.
+
+---
+
+## Static Asset Rules (apply during BUILD)
+
+| Rule | Detail |
+|------|--------|
+| Public logos | Use relative paths (`logo.svg`), not `/logo.svg` |
+| Rank-order images | Prefer `option.imageUrl` over `option.previewImageUrl` — preview `*_p.*` URLs often return 403 |
+| Footer hash links | Use plain `<a href="#">`, not `next/link` — avoids RSC prefetch on static export |
+| No AWS keys in code | JWT only in `Authorization: Bearer` header at deploy time |
+
+---
+
+## Deploy Procedure (agent executes in order)
+
+### Step 0 — Build
+
+```bash
+cd <project-root>
+yarn build   # or npm run build
+test -f "$OUT_DIR/index.html" || { echo "Missing index.html"; exit 1; }
+find "$OUT_DIR" -type f | wc -l   # must be ≤ 500
+```
+
+### Step 1 — Channel 1: manifest + start
+
+```bash
+python3 <<'PY' > /tmp/deploy-manifest.json
+import json, os, mimetypes
+from pathlib import Path
+out = Path(os.environ["OUT_DIR"])
+files = []
+for path in sorted(out.rglob("*")):
+    if not path.is_file():
+        continue
+    rel = path.relative_to(out).as_posix()
+    mime, _ = mimetypes.guess_type(rel)
+    files.append({
+        "path": rel,
+        "contentType": mime or "application/octet-stream",
+        "sizeBytes": path.stat().st_size,
+    })
+print(json.dumps({"files": files}))
+print(f"files: {len(files)}", file=__import__('sys').stderr)
+PY
+
+curl -s -X POST "$CFM_DEPLOY_API_BASE/deploy/start" \
+  -H "Authorization: Bearer $CFM_INSTANCE_ID" \
+  -H "Content-Type: application/json" \
+  -d @/tmp/deploy-manifest.json \
+  | tee /tmp/deploy-start.json
+```
+
+**Success:** JSON with `deployId`, `s3Prefix`, `uploads[]`.
+
+| Error | Fix |
+|-------|-----|
+| `401 TOKEN_EXPIRED` | Ask client for fresh instanceId JWT |
+| `503 DEPLOY_UNAVAILABLE` | EC2 hosting env misconfigured — report to operator |
+| `400 files must not exceed 500` | Reduce build output |
+
+### Step 2 — Channel 2: upload every file to S3
+
+```bash
+python3 <<'PY'
+import json, os, subprocess
+from pathlib import Path
+
+out = Path(os.environ["OUT_DIR"])
+start = json.load(open("/tmp/deploy-start.json"))
+manifest = {f["path"]: f["contentType"] for f in json.load(open("/tmp/deploy-manifest.json"))["files"]}
+failed = []
+
+for item in start["uploads"]:
+    path = item["path"]
+    url = item["uploadUrl"]
+    mime = manifest.get(path, "application/octet-stream")
+    proc = subprocess.run(
+        ["curl", "-s", "-o", "/dev/null", "-w", "%{http_code}",
+         "-X", "PUT", url, "-H", f"Content-Type: {mime}",
+         "--data-binary", f"@{out / path}"],
+        capture_output=True, text=True,
+    )
+    code = proc.stdout.strip()
+    mark = "OK" if code == "200" else "FAIL"
+    print(f"{mark} {code} {path}")
+    if code != "200":
+        failed.append(path)
+
+if failed:
+    print(f"\n{len(failed)} failed — rerun from Step 1 (presigned URLs expire)")
+    raise SystemExit(1)
+print("\nAll uploads succeeded")
+PY
+```
+
+**Success:** every line shows `OK 200`.
+
+### Step 3 — Channel 3: complete + live URL
+
+```bash
+DEPLOY_ID=$(python3 -c "import json; print(json.load(open('/tmp/deploy-start.json'))['deployId'])")
+
+curl -s -X POST "$CFM_DEPLOY_API_BASE/deploy/complete" \
+  -H "Authorization: Bearer $CFM_INSTANCE_ID" \
+  -H "Content-Type: application/json" \
+  -d "{\"deployId\":\"$DEPLOY_ID\"}" \
+  | tee /tmp/deploy-complete.json
+
+python3 -c "import json; print('\nLive URL:\n' + json.load(open('/tmp/deploy-complete.json'))['url'])"
+```
+
+**Success:**
+
+```json
+{
+  "url": "https://<cloudfront-domain>/sites/{surveyId}/{deployId}/index.html",
+  "deployId": "...",
+  "surveyId": "..."
+}
+```
+
+### Step 4 — Verify
+
+```bash
+LIVE_URL=$(python3 -c "import json; print(json.load(open('/tmp/deploy-complete.json'))['url'])")
+curl -s -o /dev/null -w "index.html: %{http_code}\n" "$LIVE_URL"
+# Optional: grep one CSS href from HTML and curl it under the deploy prefix — expect 200
+```
+
+Tell the client to open the printed URL in a browser.
+
+---
+
+## One-Command Wrapper (optional)
+
+After build, from project root:
+
+```bash
+export CFM_INSTANCE_ID="<JWT>"
+export CFM_DEPLOY_API_BASE="http://43.204.26.213:3000"
+export OUT_DIR="<absolute path to out/ or dist/>"
+
+bash templates/deploy-to-aws.sh
+# or: bash node_modules/@explorer02/cfm-survey-sdk/templates/docs/templates/deploy-to-aws.sh
+```
+
+---
+
+## Repeat Deploys
+
+Each deploy creates a **new** `deployId` folder under `sites/{surveyId}/`. Old deploys remain in S3.
+
+After UI changes: rebuild → re-run Steps 1–3 (same `CFM_INSTANCE_ID` if same survey).
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Agent fix |
+|---------|-------|-----------|
+| 403 on `/_next/static/...` | Absolute asset paths | Add `assetPrefix: "./"`, rebuild |
+| 403 on `index.html.txt?_rsc` | Missing RSC payload file | Add `cp out/index.txt out/index.html.txt` to build script |
+| 403 on `*_p.png` / `*_p.jpg` images | Preview URL used | Use `option.imageUrl \|\| option.previewImageUrl` in RankOrderScale |
+| 401 `TOKEN_EXPIRED` | JWT expired | Ask client for new instanceId |
+| 503 `DEPLOY_UNAVAILABLE` | EC2 CloudFront/S3 env wrong | Report to operator |
+| Some PUTs 403 | Presigned URLs expired (default 5 min) | Restart from Step 1; complete within window |
+| Blank page, HTML 200 | JS/CSS not uploaded or wrong paths | Re-check Channel 2 logs |
+| Survey API errors in browser | Deploy JWT ≠ SurveyPage JWT | Align `SURVEY_INSTANCE_ID` |
+
+---
+
+## Future: CLI automation (Phase 7b)
+
+`npx cfm-sdk deploy --aws` is **not implemented yet**. Use the manual flow above or `templates/deploy-to-aws.sh` until the CLI ships.