@cognior/iap-sdk 0.1.0

package/.github/copilot-instructions.md

@@ -0,0 +1,95 @@
+# Copilot Instructions — DAP SDK (TypeScript)
+
+## Summary
+This repository is a **TypeScript SDK** for rendering and managing Digital Adoption Platform (DAP) UX experiences (modals, tooltips, popovers, surveys, hotspots, walkthroughs) in the browser. It builds to a browser-ready bundle via **tsup** and exposes a global `DAP` entry point.
+
+## Repo Profile
+- **Project type:** TypeScript SDK (browser runtime)
+- **Languages:** TypeScript
+- **Build tool:** `tsup` (bundles ESM + IIFE)
+- **Target runtime:** modern browsers (ES2020)
+- **Output:** `public/dist`
+- **Repo size:** small/medium SDK repo (single package)
+
+## Build & Validation (always run in this order)
+> **Note:** These commands have not been validated in this environment; run them locally to verify.
+
+1. **Bootstrap**
+   - **Always run**: `npm install`
+   - Preconditions: Node.js installed (version not specified in repo)
+2. **Build**
+   - `npm run build`
+   - Uses `tsup` per [tsup.config.ts](tsup.config.ts)
+3. **Dev watch**
+   - `npm run dev`
+4. **Run local static server**
+   - `npm run serve` (serves `public` on port 5173)
+5. **Tests**
+   - No test script present in [package.json](package.json)
+6. **Lint**
+   - No lint script/config present
+
+### Observed/expected behaviors
+- Build output goes to `public/dist` (cleaned before build).
+- No explicit CI workflows are present in the repo root.
+- If build fails due to missing deps, re-run `npm install`.
+
+## Project Layout & Architecture
+### Core entry points
+- **SDK entry:** [src/index.ts](src/index.ts) — registers experiences and exposes API
+- **Flow normalization:** [src/flows.ts](src/flows.ts)
+- **Execution engine:** [src/core/flowEngine.ts](src/core/flowEngine.ts)
+
+### Experiences
+- [src/experiences/](src/experiences/) — modal, tooltip, popover, survey, banner, beacon, hotspots, hotspotTour, taskList, walkthrough
+
+### Utilities & services
+- [src/utils/](src/utils/) — selectors, sanitize, rule evaluation, triggers, tracking
+- [src/services/](src/services/) — flow/user/page context services
+- [src/styles/](src/styles/) — CSS-in-TS for experiences
+
+### Config & build
+- [package.json](package.json) — scripts: `build`, `dev`, `serve`
+- [tsconfig.json](tsconfig.json) — TS compile options (ES2020, strict)
+- [tsup.config.ts](tsup.config.ts) — bundling config
+- Root docs: [TRACKING.md](TRACKING.md), [USER_CONTEXT_README.md](USER_CONTEXT_README.md)
+
+### Root files (current)
+- .gitignore
+- package.json
+- TRACKING.md
+- tsconfig.json
+- tsup.config.ts
+- USER_CONTEXT_README.md
+- public/
+- src/
+
+### Next-level directories
+- `src/`
+  - config.ts
+  - flow-sequence.ts
+  - flows.ts
+  - http.ts
+  - index.ts
+  - tourUtils.ts
+  - tracking.ts
+  - core/
+  - experiences/
+  - services/
+  - state/
+  - styles/
+  - utils/
+
+## Validation & PR Safety
+- **Always run** `npm install` before build/watch.
+- **Always run** `npm run build` before completing changes.
+- There are no repo-defined test or lint scripts; treat `npm run build` as the primary validation step.
+- If adding new dependencies, update [package.json](package.json) and verify build output in `public/dist`.
+
+## Notes for efficient changes
+- Experience rendering logic lives under [src/experiences/](src/experiences/).
+- Flow execution and rule handling are centralized in [src/core/flowEngine.ts](src/core/flowEngine.ts) and [src/utils/](src/utils/).
+- Avoid changing the public API surface in [src/index.ts](src/index.ts) unless required.
+
+## Instruction Priority
+Follow this document first. Only search the repo if this file is incomplete or incorrect.

package/README.md

@@ -0,0 +1,79 @@
+# Cognior IAP SDK
+
+TypeScript SDK for rendering Intelligent Adoption Platform (IAP) experiences (modals, tooltips, popovers, surveys, hotspots, walkthroughs) in the browser. Bundled with `tsup` and exposes a global `DAP` entry point for browser usage.
+
+## Install
+
+```bash
+npm install @cognior/iap-sdk
+```
+
+## Usage
+
+### Browser (Global `DAP`)
+If you serve the bundled IIFE, it exposes `window.DAP`.
+
+```html
+<script src="./dist/index.global.js"></script>
+<script>
+  DAP.init({
+    configUrl: "/dap-config.json",
+    debug: true
+  });
+</script>
+```
+
+### ESM (Bundler)
+```ts
+import * as DAP from "@cognior/iap-sdk";
+
+await DAP.init({
+  configUrl: "/dap-config.json",
+  debug: true
+});
+```
+
+### Initialization
+`DAP.init` accepts a config URL and optional debug/user parameters. See [`init`](src/index.ts) and [`DapConfig`](src/config.ts).
+
+```ts
+await DAP.init({
+  configUrl: "https://your-api.com/config",
+  debug: true,
+  user: {
+    id: "user-123",
+    role: "Admin",
+    email: "admin@company.com",
+    attributes: { plan: "Premium" }
+  }
+});
+```
+
+### Required Config Fields
+The config returned by `configUrl` must include:
+
+```json
+{
+  "organizationid": "string",
+  "siteid": "string",
+  "apikey": "string",
+  "apiurl": "string"
+}
+```
+
+See [`DapConfig`](src/config.ts).
+
+## Tracking
+Automatic tracking is enabled by default. 
+
+## User Context
+User context is optional but enables personalization. 
+
+## Public API (high-level)
+- `DAP.init(...)` — initialize SDK
+- `DAP.executeFlow(...)` — execute a flow object
+- `DAP.registerFlow(...)` — register flow by ID
+- `DAP.startFlow(flowId)` — start a flow by ID
+
+## License
+UNLICENSED

package/TRACKING.md

@@ -0,0 +1,105 @@
+# DAP Flow Activity Tracking
+
+The DAP SDK now includes functionality for tracking user interactions with DAP flows and experiences, sending this activity data to the DAP backend. This document explains how to use this feature focused on tracking DAP-related user activities.
+
+## Tracking Endpoint
+
+The SDK uses the following endpoint for tracking user actions:
+
+```
+POST /api/iap-experience/{organizationId}/{siteCollectionId}/track-action/{flowId}
+```
+
+The request body includes:
+
+```json
+{
+  "stepId": "string",
+  "actionType": "string",
+  "actionData": "string",
+  "sessionId": "string",
+  "occurredAt": "2025-09-24T15:05:57.569Z",
+  "clientInfo": {
+    "userId": "string",
+    "clientIP": "string", 
+    "userAgent": "string",
+    "locale": "string"
+  },
+  "elementSelector": "string",
+  "elementContext": "string"
+}
+```
+
+## Usage
+
+### Automatic Tracking
+
+The SDK can automatically track common user interactions like clicks, form submissions, and input changes. This is enabled by default when you initialize the DAP SDK:
+
+```javascript
+DAP.init({ 
+  configUrl: '../dap-config.json', 
+  debug: true,
+  enableTracking: true // This is the default
+});
+```
+
+To disable automatic tracking at initialization:
+
+```javascript
+DAP.init({ 
+  configUrl: '../dap-config.json', 
+  debug: true,
+  enableTracking: false
+});
+```
+
+You can also enable or disable tracking after initialization:
+
+```javascript
+// Enable tracking
+DAP.enableActionTracking();
+
+// Disable tracking
+DAP.disableActionTracking();
+```
+
+### Manual Tracking
+
+You can manually track specific DAP flow activities:
+
+```javascript
+DAP.trackFlowActivity({
+  actionType: 'flow_interaction',
+  actionData: JSON.stringify({
+    flowType: 'tutorial',
+    interactionType: 'step_complete',
+    stepName: 'feature_introduction'
+  }),
+  stepId: 'tutorial-step-1',
+  elementSelector: '.dap-tutorial-container'
+});
+```
+
+## Tracked Flow Activities
+
+The tracking system focuses on DAP flow activities and captures:
+
+1. **Flow Impressions** - When a DAP flow is presented to the user
+2. **Flow Interactions** - When users interact with DAP components (modals, tooltips, etc.)
+3. **Survey Interactions** - When users engage with DAP surveys
+4. **Flow Completions** - When users complete a DAP flow sequence 
+5. **Step Transitions** - When users navigate between steps in a flow
+
+## Data Privacy
+
+The tracking system is designed with privacy in mind:
+
+- Password fields are automatically redacted
+- Credit card fields are automatically redacted
+- No personally identifiable information (PII) is tracked unless explicitly provided
+- Tracking can be disabled at any time
+
+## Session Management
+
+The SDK automatically creates and maintains a session ID stored in the browser's session storage. This helps correlate actions within the same browsing session.

package/USER_CONTEXT_README.md

@@ -0,0 +1,284 @@
+# DAP SDK User Context Implementation
+
+## 🎯 Overview
+
+The DAP SDK now includes **Standard User Context Handling** that allows host applications to provide user data explicitly for:
+- Flow targeting and execution  
+- Rule evaluation based on user properties
+- Analytics tracking with user context
+- Safe fallback for anonymous users
+
+## 🔒 Security Principles
+
+✅ **NEVER infers user identity** - only accepts explicitly provided data  
+✅ **Host application is source of truth** for user data  
+✅ **Defensive programming** - works safely when user data is missing  
+✅ **No DOM scraping, cookie reading, or JWT parsing**  
+
+## 📋 User Model
+
+```typescript
+interface DapUser {
+  id: string;                           // Required: unique user identifier
+  role?: string;                        // Optional: user role/type
+  email?: string;                       // Optional: user email
+  attributes?: Record<string, string>;  // Optional: custom user attributes
+}
+```
+
+## 🚀 Quick Start
+
+### 1. SDK Initialization
+
+```javascript
+// Initialize without user (anonymous mode)
+await DAP.init({
+  configUrl: "https://your-api.com/config",
+  debug: true
+});
+
+// Initialize with user context
+await DAP.init({
+  configUrl: "https://your-api.com/config", 
+  debug: true,
+  user: {
+    id: "user-12345",
+    role: "Admin", 
+    email: "admin@company.com",
+    attributes: {
+      department: "Engineering",
+      plan: "Premium"
+    }
+  }
+});
+```
+
+### 2. User Context Management
+
+```javascript
+// Set user context
+DAP.setUser({
+  id: "user-67890",
+  role: "Manager",
+  email: "manager@company.com",
+  attributes: {
+    team: "Sales",
+    region: "US-West"
+  }
+});
+
+// Update existing user
+DAP.updateUser({
+  role: "Senior Manager",  // Updated role
+  attributes: {
+    team: "Sales",
+    region: "US-West", 
+    certification: "Advanced"  // New attribute
+  }
+});
+
+// Get current user
+const user = DAP.getUser();
+console.log(user);
+
+// Clear user context
+DAP.clearUser();
+```
+
+## 🎛️ Flow Execution Logic
+
+### Without User Context
+- SDK generates anonymous fallback user ID: `dap-anon-<timestamp>-<random>`
+- Stored in `sessionStorage` as `dap_anonymous_user_id`
+- Flows execute unless they explicitly require user properties
+- Analytics track with `isAnonymous: true`
+
+### With User Context  
+- Real user data used for flow targeting
+- Rules can evaluate user properties 
+- Analytics include full user context
+- Flows execute based on user-specific rules
+
+### Flow Initialization Timing
+- Waits for `DOMContentLoaded` event
+- Blocks flow execution if user context is required but missing
+- Re-evaluates flows when `setUser()` is called
+
+## 📏 Rule Engine Integration
+
+Rules can now reference user properties safely:
+
+```javascript
+// Example rule conditions
+{
+  "property": "user.role",
+  "operator": "Equals", 
+  "value": "Admin"
+}
+
+{
+  "property": "user.attributes.plan",
+  "operator": "Equals",
+  "value": "Premium"
+}
+```
+
+### Supported Properties
+- `user.id` - User identifier
+- `user.role` - User role/type  
+- `user.email` - User email address
+- `user.attributes.<key>` - Custom user attributes
+
+### Rule Safety
+- Missing user → property evaluates to `null`
+- Missing property → evaluates to `null` 
+- Rules fail gracefully without throwing errors
+- Defensive logging for debugging
+
+## 📊 Analytics Integration
+
+All tracking payloads automatically include:
+
+```javascript
+{
+  userId: "user-12345",           // User ID or anonymous ID
+  userRole: "Admin",              // User role (if available)
+  userAttributes: {               // User attributes (if available)
+    department: "Engineering",
+    plan: "Premium"
+  },
+  isAnonymous: false,            // Whether user is anonymous
+  // ... other tracking fields
+}
+```
+
+### Anonymous User Analytics
+```javascript
+{
+  userId: "dap-anon-1641234567-abc123",
+  isAnonymous: true
+  // role and attributes will be undefined
+}
+```
+
+## 🛠️ API Reference
+
+### Initialization
+```typescript
+DAP.init(options: {
+  configUrl: string;
+  debug?: boolean;
+  screenId?: string;
+  user?: DapUser;          // 🆕 Optional user context
+}): Promise<void>
+```
+
+### User Management
+```typescript
+DAP.setUser(user: DapUser): void
+DAP.updateUser(partialUser: Partial<DapUser>): void  
+DAP.getUser(): DapUser | null
+DAP.clearUser(): void
+```
+
+### Debug Utilities
+```typescript
+DAP.getUserState(): {
+  hasUser: boolean;
+  userId: string;
+  userRole?: string; 
+  isAnonymous: boolean;
+  attributeCount: number;
+}
+```
+
+## 🔧 Implementation Details
+
+### UserContextService
+- **Singleton service** managing user state
+- **In-memory storage** as source of truth
+- **sessionStorage persistence** for page reloads
+- **Event system** for user context changes
+- **Defensive property access** for rule evaluation
+
+### Flow Engine Integration
+- **User context validation** before flow execution
+- **Automatic re-evaluation** when user context changes
+- **Graceful handling** of missing user data
+
+### Analytics Enhancement
+- **Automatic user context injection** in all tracking payloads
+- **Anonymous user handling** with fallback IDs
+- **Privacy-safe data sanitization**
+
+## ⚡ Performance Considerations
+
+- **Lightweight singleton** - minimal memory footprint
+- **Efficient sessionStorage** operations with error handling
+- **Event-driven updates** - no polling or watchers
+- **Lazy initialization** - services created on demand
+
+## 🧪 Testing
+
+See `test-user-context.js` for comprehensive test examples covering:
+- SDK initialization with/without user
+- User context management lifecycle
+- Rule evaluation with user properties  
+- Analytics context generation
+- Anonymous user fallback behavior
+
+## 🔄 Migration Guide
+
+### For Existing SDK Users
+- **Zero breaking changes** - all existing functionality preserved
+- **Optional user parameter** in `init()` method
+- **Backward compatible** - works without user context
+
+### For New Implementations
+- **Start with anonymous mode** for immediate functionality
+- **Add user context** when authentication is available
+- **Use rule targeting** for personalized experiences
+
+## 📝 Examples
+
+### E-commerce Platform
+```javascript
+// After user login
+DAP.setUser({
+  id: customer.id,
+  role: customer.tier,  // "Bronze", "Silver", "Gold"
+  email: customer.email,
+  attributes: {
+    country: customer.address.country,
+    purchaseHistory: customer.totalOrders.toString(),
+    lastPurchase: customer.lastOrderDate
+  }
+});
+
+// Target premium features to Gold customers
+// Rule: user.role === "Gold"
+```
+
+### SaaS Application  
+```javascript
+// After authentication
+DAP.setUser({
+  id: user.id,
+  role: user.role,  // "Admin", "User", "Viewer"
+  email: user.email,
+  attributes: {
+    organization: user.orgId,
+    plan: subscription.planType,
+    features: user.enabledFeatures.join(",")
+  }
+});
+
+// Show admin onboarding only to admins
+// Rule: user.role === "Admin"
+```
+
+---
+
+## 🎉 Ready to Use!
+
+The User Context system is now fully integrated and ready for production use. All components work together seamlessly to provide a robust, secure, and flexible user context management solution for the DAP SDK.