@encatch/web-sdk 0.0.35-beta.8 → 1.0.0-beta.0

package/README.md

@@ -1,756 +1,258 @@
-# Encatch Web SDK
+# @encatch/web-sdk
 
-A powerful, lightweight JavaScript SDK for collecting user feedback and running surveys on web applications. Built with Preact and TypeScript, the Encatch Web SDK provides intelligent trigger-based feedback collection with advanced targeting and frequency control.
+A lightweight, type-safe JavaScript SDK for integrating Encatch forms and surveys into your web application.
 
 ## Features
 
-- **Intelligent Triggers**: Automatically display feedback based on user behavior
-  - Page load triggers
-  - Custom event triggers
-  - Scroll-based triggers
-  - Time-delayed triggers
-- **User Session Management**: Track and manage user sessions with device fingerprinting
-- **Frequency Control**: Configure feedback display frequency and scheduling
-- **Multi-language Support**: Display feedback in multiple languages
-- **Theme Support**: Light and dark mode with custom CSS
-- **Prepopulated Answers**: Pre-fill feedback forms with known data
-- **Event Tracking**: Track user interactions and custom events
-- **TypeScript Support**: Fully typed API for better developer experience
-- **Lightweight**: Minimal bundle size with optimized performance
+- **Lightweight**: Minimal stub that loads the full implementation asynchronously
+- **Type-safe**: Full TypeScript support with comprehensive type definitions
+- **Queue-based**: Commands are queued until the SDK is ready, ensuring no calls are lost
+- **Framework agnostic**: Works with any JavaScript framework or vanilla JS
 
 ## Installation
 
-### Via Script Tag (Recommended)
-
-Add the following script to your HTML file before the closing `</head>` tag:
-
-```html
-<script>
-  !function(){if(!window.encatch){var e={_i:[],apiKey:"",config:{host:"https://your-host.com",autoStartEnabled:!1,autoStartSessionDisabled:!0,themeMode:"light",language:"en",customCssLink:""},initialized:!1,chunkUrlLoader:function(e){return window.encatch.config.host+e},init:function(n,t){if(!("initialized"in window.encatch&&window.encatch.initialized)){if(window.encatch.apiKey=n,t?.host&&(window.encatch.config.host=t.host),t?.identity&&(window.encatch.config.identity=t.identity),void 0!==t?.autoStartSessionDisabled&&(window.encatch.config.autoStartSessionDisabled=t.autoStartSessionDisabled),void 0!==t?.processAfterIdentitySet?window.encatch.config.processAfterIdentitySet=t.processAfterIdentitySet:window.encatch.config.processAfterIdentitySet=!1,void 0!==t?.autoStartEnabled&&(window.encatch.config.autoStartEnabled=t.autoStartEnabled),t?.themeMode?window.encatch.config.themeMode=t.themeMode:window.encatch.config.themeMode="light",t?.language?window.encatch.config.language=t.language:window.encatch.config.language="en",t?.customCssLink&&(window.encatch.config.customCssLink=t.customCssLink),t?.setUser&&(window.encatch.config.setUser=t.setUser),window.encatch.initialized=!0,!import.meta.env.VITE_PATH_PREFIX||import.meta.env.VITE_PATH_PREFIX.startsWith("/")||(import.meta.env.VITE_PATH_PREFIX="/"+import.meta.env.VITE_PATH_PREFIX),import.meta.env.VITE_PATH_PREFIX=import.meta.env.VITE_PATH_PREFIX.replace(/\/+$/,""),scriptSrc=`${window.encatch.config.host}${import.meta.env.VITE_PATH_PREFIX||""}/encatch-web-sdk.js`,(script=document.createElement("script")).src=scriptSrc,script.type="module",script.async=!0,firstHeadElement=document.head.firstChild)firstHeadElement?document.head.insertBefore(script,firstHeadElement):document.head.appendChild(script);var o=document.createElement("div");o.id="enisght-root",document.body.appendChild(o)}}};window.encatch=e,["trackEvent","stop","start","setUser","setThemeMode","setLanguage","openFeedbackById","openFeedbackByName","verifyFeedbackIds","forceFetchEligibleFeedbacks","capturePageScrollEvent"].forEach((function(n){e[n]=function(){for(var t=arguments.length,o=new Array(t),i=0;i<t;i++)o[i]=arguments[i];window.encatch._i.push([n].concat(o))}}))}}();
-</script>
-```
-
-Then initialize the SDK:
-
-```html
-<script>
-  encatch.init('YOUR_API_KEY', {
-    host: 'https://your-host.com',
-    autoStartEnabled: true
-  });
-</script>
-```
-
-### Via NPM (For Module Bundlers)
+### NPM / Yarn / PNPM
 
 ```bash
 npm install @encatch/web-sdk
+# or
+yarn add @encatch/web-sdk
+# or
+pnpm add @encatch/web-sdk
 ```
 
-```javascript
-import '@encatch/web-sdk';
+### CDN / Script Tag
 
-encatch.init('YOUR_API_KEY', {
-  host: 'https://your-host.com',
-  autoStartEnabled: true
-});
+```html
+<script src="https://unpkg.com/@encatch/web-sdk/dist/encatch.iife.js"></script>
 ```
 
 ## Quick Start
 
-### Basic Setup
+### ES Modules
 
 ```javascript
-// Initialize the SDK
-encatch.init('YOUR_API_KEY', {
-  host: 'https://your-host.com',
-  autoStartEnabled: true,
-  themeMode: 'light',
-  language: 'en'
-});
+import { _encatch } from '@encatch/web-sdk';
 
-// Set user identity (optional)
-encatch.setUser('user-123', {
-  $set: {
-    email: 'user@example.com',
-    name: 'John Doe',
-    plan: 'premium'
-  }
-});
+// Initialize with your API key
+_encatch.init('YOUR_API_KEY');
 
-// Track custom events
-encatch.trackEvent('button_clicked', {
-  path: '/dashboard',
-  button_id: 'upgrade-button'
+// Identify the user
+_encatch.identifyUser('user-123', {
+  email: 'user@example.com',
+  name: 'John Doe',
 });
 ```
 
-### Manual Trigger
+### Script Tag
 
-```javascript
-// Open feedback by ID
-encatch.openFeedbackById('feedback-config-id-123');
-
-// Open feedback by name
-encatch.openFeedbackByName('Customer Satisfaction Survey');
-
-// With theme and language override
-encatch.openFeedbackById('feedback-config-id-123', 'dark', 'es');
-```
-
-## Configuration Options
-
-### Initialization Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `host` | `string` | - | **Required**. The host URL for the Encatch API |
-| `autoStartEnabled` | `boolean` | `false` | Automatically start fetching eligible feedbacks |
-| `autoStartSessionDisabled` | `boolean` | `true` | Disable automatic session management |
-| `processAfterIdentitySet` | `boolean` | `false` | Wait for user identity before processing |
-| `themeMode` | `'light' \| 'dark'` | `'light'` | Default theme mode |
-| `language` | `string` | `'en'` | Default language code |
-| `customCssLink` | `string` | - | URL to custom CSS file |
-| `setUser` | `UserInfo` | - | Initial user identity |
-| `customProperties` | `Record<string, string>` | - | Custom properties for targeting |
-| `onSessionDisabled` | `(action, message) => void` | - | Callback when session functions are disabled |
-
-### Example: Complete Configuration
-
-```javascript
-encatch.init('YOUR_API_KEY', {
-  host: 'https://your-host.com',
-  autoStartEnabled: true,
-  autoStartSessionDisabled: false,
-  themeMode: 'light',
-  language: 'en',
-  customCssLink: 'https://your-cdn.com/custom-theme.css',
-  setUser: {
-    userId: 'user-123',
-    traits: {
-      $set: {
-        email: 'user@example.com',
-        plan: 'premium'
-      }
-    }
-  },
-  onSessionDisabled: (action, message) => {
-    console.warn(`Session action blocked: ${action} - ${message}`);
-  }
-});
+```html
+<script src="https://unpkg.com/@encatch/web-sdk/dist/encatch.iife.js"></script>
+<script>
+  // The SDK is available as window._encatch
+  _encatch.init('YOUR_API_KEY');
+  
+  _encatch.identifyUser('user-123', {
+    email: 'user@example.com',
+    name: 'John Doe',
+  });
+</script>
 ```
 
 ## API Reference
 
-### `init(apiKey, options)`
+### `init(apiKey, config?)`
 
-Initialize the Encatch SDK.
+Initialize the SDK with your API key. This must be called before any other methods. It triggers the loading of the remote implementation script.
 
 ```javascript
-encatch.init('YOUR_API_KEY', {
-  host: 'https://your-host.com',
-  autoStartEnabled: true
+_encatch.init('YOUR_API_KEY', {
+  webHost: 'https://custom-cdn.example.com', // Optional: override default web host (script will be loaded from webHost + '/s/sdk/v1/encatch.js')
+  theme: 'dark', // Optional: 'light', 'dark', or 'system' (default: 'system')
 });
 ```
 
-### `start(userId?, traits?)`
+### `identifyUser(id, traits?, options?)`
 
-Start the SDK and optionally set user identity. Useful when `autoStartEnabled: false`.
+Identify the current user. The `id` is required, traits and options are optional.
 
 ```javascript
-// Start without user
-encatch.start();
-
-// Start with user identity
-encatch.start('user-123', {
-  $set: {
-    email: 'user@example.com',
-    name: 'John Doe'
-  }
+// Simple - just ID
+_encatch.identifyUser('user-123');
+
+// With traits
+_encatch.identifyUser('user-123', {
+  email: 'user@example.com', // Optional: user's email
+  name: 'John Doe',          // Optional: user's full name
+  plan: 'premium',           // Optional: custom traits
+  signed_up_at: new Date(),  // Optional: date fields (must end with _at or _date)
 });
-```
 
-### `stop()`
-
-Stop the SDK. Behavior depends on initialization:
-
-- If initialized with `autoStartEnabled: false`: Clears all data, feedbacks, and frequency tracking
-- If initialized with `autoStartEnabled: true`: Makes user anonymous but retains feedbacks
-
-```javascript
-encatch.stop();
-```
-
-### `setUser(userId?, traits?)`
-
-Set or update user identity.
-
-```javascript
-// Set user identity
-encatch.setUser('user-123', {
-  $set: { email: 'user@example.com', plan: 'premium' },
-  $set_once: { signup_date: '2024-01-01' },
-  $counter: { logins: 1 },
-  $unset: ['temp_property']
-});
-
-// Make user anonymous
-encatch.setUser();
-```
-
-#### User Traits Operators
-
-- `$set`: Set property value (overwrites existing)
-- `$set_once`: Set only if property doesn't exist
-- `$counter`: Increment counter by value
-- `$unset`: Remove properties (array of property names)
-
-### `trackEvent(eventName, properties?)`
-
-Track custom events for trigger matching.
-
-```javascript
-encatch.trackEvent('purchase_completed', {
-  path: '/checkout/success',
-  product_id: 'prod-123',
-  amount: 99.99
+// With traits and options
+_encatch.identifyUser('user-123', {
+  email: 'user@example.com',
+  name: 'John Doe',
+}, {
+  locale: 'en',              // Optional: user's locale
+  country: 'US',             // Optional: user's country
 });
 ```
 
-### `openFeedbackById(feedbackConfigId, theme?, language?, event?, customProperties?, prepopulatedAnswers?)`
+### `setLocale(locale)`
 
-Manually open a feedback form by its configuration ID.
+Set the user's preferred language.
 
 ```javascript
-// Basic usage
-encatch.openFeedbackById('feedback-config-id-123');
-
-// With theme and language override
-encatch.openFeedbackById('feedback-config-id-123', 'dark', 'es');
-
-// With prepopulated answers
-encatch.openFeedbackById('feedback-config-id-123', 'light', 'en', undefined, undefined, [
-  {
-    sectionIndex: 0,
-    questionIndex: 0,
-    value: { text: 'Pre-filled answer' }
-  }
-]);
+_encatch.setLocale('fr,en,es'); // Comma-separated ISO 639-1 codes
 ```
 
-### `openFeedbackByName(feedbackName, theme?, language?, event?, customProperties?, prepopulatedAnswers?)`
+### `setCountry(country)`
 
-Manually open a feedback form by its name.
+Set the user's country.
 
 ```javascript
-encatch.openFeedbackByName('Customer Satisfaction Survey');
-
-// With options
-encatch.openFeedbackByName('NPS Survey', 'dark', 'es');
+_encatch.setCountry('FR'); // ISO 3166 country code
 ```
 
-### `setThemeMode(theme)`
+### `setTheme(theme)`
 
-Change the theme mode dynamically.
+Set the theme. Default is 'system'.
 
 ```javascript
-encatch.setThemeMode('dark');
-encatch.setThemeMode('light');
+_encatch.setTheme('dark'); // 'light', 'dark', or 'system'
+_encatch.setTheme('light');
+_encatch.setTheme('system'); // Follows system preference
 ```
 
-### `setLanguage(language)`
+### `trackEvent(eventName)`
 
-Change the language dynamically.
+Track a custom event.
 
 ```javascript
-encatch.setLanguage('es'); // Spanish
-encatch.setLanguage('fr'); // French
-encatch.setLanguage('en'); // English
+_encatch.trackEvent('button_clicked');
+_encatch.trackEvent('purchase_completed');
 ```
 
-### `forceFetchEligibleFeedbacks()`
+### `startSession()`
 
-Force refresh the list of eligible feedbacks.
+Manually start a new session. Useful after user login.
 
 ```javascript
-await encatch.forceFetchEligibleFeedbacks();
+_encatch.startSession();
 ```
 
-### `verifyFeedbackIds(feedbackIds)`
+### `resetUser()`
 
-Verify which feedback IDs are currently eligible.
+Reset the current user (logout). Reverts the SDK to anonymous mode.
 
 ```javascript
-const validIds = encatch.verifyFeedbackIds([
-  'feedback-id-1',
-  'feedback-id-2',
-  'feedback-id-3'
-]);
-console.log('Valid feedback IDs:', validIds);
+_encatch.resetUser();
 ```
 
-### `capturePageScrollEvent(scrollPercent)`
+### `showForm(formId, force?)`
 
-Manually trigger scroll-based feedback.
+Show a specific form by ID.
 
 ```javascript
-// Track scroll percentage
-window.addEventListener('scroll', () => {
-  const scrollPercent = (window.scrollY / (document.documentElement.scrollHeight - window.innerHeight)) * 100;
-  encatch.capturePageScrollEvent(`${scrollPercent}%`);
-});
+_encatch.showForm('form-abc-123');
+_encatch.showForm('form-abc-123', true); // Force show even if already shown
 ```
 
-## Event Tracking
+### `addToResponse(questionId, value)`
 
-### Automatic Page Tracking
-
-The SDK automatically tracks page changes in single-page applications:
+Prepopulate a form response.
 
 ```javascript
-// Page changes are tracked automatically
-// Triggers "pageLoad" event for configured triggers
+_encatch.addToResponse('question-1', 'Pre-filled answer');
 ```
 
-### Custom Events
+### `on(event, callback)`
 
-Track custom events for business logic:
+Subscribe to SDK events. Returns an unsubscribe function.
 
 ```javascript
-// E-commerce example
-encatch.trackEvent('product_viewed', {
-  path: '/products/123',
-  category: 'electronics',
-  price: 299.99
+const unsubscribe = _encatch.on('form:submit', (payload) => {
+  console.log('Form submitted:', payload);
 });
 
-encatch.trackEvent('add_to_cart', {
-  path: '/products/123',
-  product_id: 'prod-123'
-});
-
-encatch.trackEvent('checkout_started', {
-  path: '/checkout',
-  cart_value: 599.98
-});
+// Later, to unsubscribe:
+unsubscribe();
 ```
 
-### Scroll Tracking
-
-```javascript
-// Automatic scroll tracking (if configured in feedback triggers)
-// Or manual tracking:
-let scrollTriggered = false;
+### `off(event, callback)`
 
-window.addEventListener('scroll', () => {
-  const scrollPercent = (window.scrollY / (document.documentElement.scrollHeight - window.innerHeight)) * 100;
-
-  if (scrollPercent > 50 && !scrollTriggered) {
-    encatch.capturePageScrollEvent('50%');
-    scrollTriggered = true;
-  }
-});
-```
-
-## Advanced Usage
-
-### Prepopulated Answers
-
-Pre-fill feedback forms with known data:
+Unsubscribe from SDK events.
 
 ```javascript
-encatch.openFeedbackById('feedback-config-id', 'light', 'en', undefined, undefined, [
-  {
-    sectionIndex: 0,  // First section
-    questionIndex: 0, // First question
-    value: { text: 'Pre-filled text answer' }
-  },
-  {
-    sectionIndex: 0,
-    questionIndex: 1,
-    value: { rating: 5 }
-  }
-]);
-```
-
-### Custom Properties for Targeting
-
-Pass custom properties for advanced targeting:
-
-```javascript
-encatch.openFeedbackById(
-  'feedback-config-id',
-  'light',
-  'en',
-  undefined,
-  {
-    user_segment: 'premium',
-    feature_flag: 'beta_features',
-    experiment_group: 'variant_a'
-  }
-);
-```
-
-### Session Management
-
-```javascript
-// Disable automatic session management
-encatch.init('YOUR_API_KEY', {
-  host: 'https://your-host.com',
-  autoStartSessionDisabled: false
-});
-
-// Manual session control (when autoStartSessionDisabled: false)
-encatch.start(); // Start a new session
-encatch.stop();  // End current session
-```
-
-### Dynamic Theme Switching
-
-```javascript
-// Listen to system theme changes
-const darkModeQuery = window.matchMedia('(prefers-color-scheme: dark)');
-
-darkModeQuery.addEventListener('change', (e) => {
-  encatch.setThemeMode(e.matches ? 'dark' : 'light');
-});
-
-// Or use a theme toggle
-function toggleTheme() {
-  const currentTheme = getCurrentTheme(); // Your theme logic
-  encatch.setThemeMode(currentTheme === 'dark' ? 'light' : 'dark');
-}
-```
-
-### Custom CSS Styling
-
-```javascript
-// Option 1: Provide custom CSS URL during initialization
-encatch.init('YOUR_API_KEY', {
-  host: 'https://your-host.com',
-  customCssLink: 'https://your-cdn.com/custom-encatch-theme.css'
-});
-
-// Option 2: Configure custom CSS per feedback in the Encatch dashboard
-```
-
-### Conditional Feedback Display
-
-```javascript
-// Only show feedback to premium users
-if (user.plan === 'premium') {
-  encatch.openFeedbackById('premium-user-feedback');
+function handleSubmit(payload) {
+  console.log('Form submitted:', payload);
 }
 
-// Show different feedback based on user journey
-if (isNewUser) {
-  encatch.openFeedbackByName('Onboarding Feedback');
-} else {
-  encatch.openFeedbackByName('Feature Usage Survey');
-}
-```
-
-## Form Event Listeners
-
-The SDK provides two approaches for listening to feedback form events: **config-based** and **runtime-based**.
-
-### Available Form Events
-
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `form:submit` | `{ feedbackIdentifier: string, feedbackConfigurationId: string, completionTimeInSeconds: number, response: Object }` | Emitted when the user completes and submits the feedback form |
-| `form:view` | `{ feedbackIdentifier: string, feedbackConfigurationId: string }` | Emitted when the feedback form is displayed to the user |
-| `form:close` | `{ feedbackIdentifier: string, feedbackConfigurationId: string }` | Emitted when the user closes the feedback form (with or without submitting) |
-| `form:questionAnswered` | `{ questionId: string, answer: Object }` | Emitted when the user answers a question |
-| `form:sectionChange` | `{ sectionIndex: number }` | Emitted when the user navigates to a different section |
-| `form:error` | `{ error: string }` | Emitted when an error occurs during form interaction |
-
-### Approach 1: Config-Based (Recommended)
-
-Define event handlers during SDK initialization using the `onFormEvent` callback:
-
-```javascript
-encatch.init('YOUR_API_KEY', {
-  host: 'https://your-host.com',
-  autoStartEnabled: true,
-  onFormEvent: (formEvent) => {
-    // Listen to form submission
-    formEvent.onSubmit((data) => {
-      console.log('Form submitted:', data);
-      console.log('Feedback ID:', data.feedbackIdentifier);
-      console.log('Config ID:', data.feedbackConfigurationId);
-      console.log('Completion time:', data.completionTimeInSeconds);
-
-      // Send to analytics
-      analytics.track('Feedback Submitted', {
-        feedbackId: data.feedbackIdentifier,
-        configId: data.feedbackConfigurationId
-      });
-    });
-
-    // Listen to form view
-    formEvent.onView((data) => {
-      console.log('Form viewed:', data);
-    });
-
-    // Listen to form close
-    formEvent.onClose((data) => {
-      console.log('Form closed:', data);
-    });
-
-    // Listen to question answered
-    formEvent.onQuestionAnswered((data) => {
-      console.log('Question answered:', data.questionId, data.answer);
-    });
-
-    // Listen to section change
-    formEvent.onSectionChange((data) => {
-      console.log('Section changed to:', data.sectionIndex);
-    });
-
-    // Listen to errors
-    formEvent.onError((data) => {
-      console.error('Form error:', data.error);
-    });
-  }
-});
-```
-
-### Approach 2: Runtime-Based
-
-Subscribe to events at runtime using the `encatch.on()` method:
-
-```javascript
-// Subscribe to form submission
-const unsubscribeSubmit = encatch.on('form:submit', (data) => {
-  console.log('Form submitted:', data);
-  alert(`Feedback submitted! ID: ${data.feedbackIdentifier}`);
-});
-
-// Subscribe to form view
-const unsubscribeView = encatch.on('form:view', (data) => {
-  console.log('Form viewed:', data);
-});
-
-// Subscribe to form close
-const unsubscribeClose = encatch.on('form:close', (data) => {
-  console.log('Form closed:', data);
-});
-
-// Subscribe to question answered
-const unsubscribeQuestion = encatch.on('form:questionAnswered', (data) => {
-  console.log('Question answered:', data);
-});
-
-// Subscribe to section change
-const unsubscribeSection = encatch.on('form:sectionChange', (data) => {
-  console.log('Section changed:', data);
-});
-
-// Subscribe to errors
-const unsubscribeError = encatch.on('form:error', (data) => {
-  console.error('Form error:', data);
-});
-
-// Unsubscribe when no longer needed
-unsubscribeSubmit();
-unsubscribeView();
-```
-
-### Integration Examples
-
-#### Google Analytics Integration
-
-```javascript
-encatch.init('YOUR_API_KEY', {
-  host: 'https://your-host.com',
-  autoStartEnabled: true,
-  onFormEvent: (formEvent) => {
-    formEvent.onView((data) => {
-      gtag('event', 'feedback_viewed', {
-        feedback_id: data.feedbackIdentifier,
-        config_id: data.feedbackConfigurationId
-      });
-    });
-
-    formEvent.onSubmit((data) => {
-      gtag('event', 'feedback_submitted', {
-        feedback_id: data.feedbackIdentifier,
-        config_id: data.feedbackConfigurationId,
-        completion_time: data.completionTimeInSeconds
-      });
-    });
-
-    formEvent.onClose((data) => {
-      gtag('event', 'feedback_closed', {
-        feedback_id: data.feedbackIdentifier
-      });
-    });
-  }
-});
-```
+_encatch.on('form:submit', handleSubmit);
 
-#### Segment Analytics Integration
-
-```javascript
-encatch.init('YOUR_API_KEY', {
-  host: 'https://your-host.com',
-  autoStartEnabled: true,
-  onFormEvent: (formEvent) => {
-    formEvent.onSubmit((data) => {
-      analytics.track('Feedback Completed', {
-        feedbackId: data.feedbackIdentifier,
-        configId: data.feedbackConfigurationId,
-        duration: data.completionTimeInSeconds
-      });
-    });
-
-    formEvent.onQuestionAnswered((data) => {
-      analytics.track('Question Answered', {
-        questionId: data.questionId,
-        answerType: data.answer.answer_type
-      });
-    });
-  }
-});
+// Later:
+_encatch.off('form:submit', handleSubmit);
 ```
 
-#### Custom Data Layer (GTM)
+## Event Types
 
-```javascript
-encatch.init('YOUR_API_KEY', {
-  host: 'https://your-host.com',
-  autoStartEnabled: true,
-  onFormEvent: (formEvent) => {
-    formEvent.onSubmit((data) => {
-      window.dataLayer = window.dataLayer || [];
-      window.dataLayer.push({
-        event: 'feedback_submitted',
-        feedbackId: data.feedbackIdentifier,
-        configId: data.feedbackConfigurationId,
-        completionTime: data.completionTimeInSeconds
-      });
-    });
-  }
-});
-```
-
-#### CRM Integration (e.g., Salesforce, HubSpot)
-
-```javascript
-encatch.init('YOUR_API_KEY', {
-  host: 'https://your-host.com',
-  autoStartEnabled: true,
-  onFormEvent: (formEvent) => {
-    formEvent.onSubmit(async (data) => {
-      // Send to your CRM
-      await fetch('https://your-crm.com/api/feedback', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-          feedbackId: data.feedbackIdentifier,
-          userId: window.currentUserId,
-          response: data.response,
-          timestamp: new Date().toISOString()
-        })
-      });
-    });
-  }
-});
-```
+| Event | Description |
+|-------|-------------|
+| `form:show` | Fired when a form is displayed |
+| `form:submit` | Fired when a form is submitted |
+| `form:close` | Fired when a form is closed |
+| `form:complete` | Fired when a form is completed |
+| `form:error` | Fired when an error occurs |
 
 ## TypeScript Support
 
-The SDK is fully typed. TypeScript definitions are included:
+The SDK is written in TypeScript and includes full type definitions.
 
 ```typescript
-import '@encatch/web-sdk';
-
-// All methods are typed
-encatch.init('YOUR_API_KEY', {
-  host: 'https://your-host.com',
-  autoStartEnabled: true,
-  themeMode: 'light', // Type: 'light' | 'dark'
-  language: 'en'
-});
-
-// User traits are typed
-encatch.setUser('user-123', {
-  $set: { email: 'user@example.com' },
-  $set_once: { signup_date: '2024-01-01' },
-  $counter: { logins: 1 },
-  $unset: ['temp_field']
-});
-
-// Event properties are typed
-encatch.trackEvent('custom_event', {
-  path: '/page',
-  event: 'click'
-});
-```
+import { _encatch, UserTraits, EncatchConfig, EventType } from '@encatch/web-sdk';
 
-## Development
-
-### Prerequisites
-
-- Node.js 18+
-- pnpm
-
-### Setup
-
-```bash
-# Install dependencies
-pnpm install
-
-# Start development server
-pnpm dev
+// Example with $set operation
+const userTraits: UserTraits = {
+  $set: {
+    email: 'user@example.com',
+    name: 'John Doe',
+    customField: 'value',
+  },
+};
 
-# Build for production
-pnpm build
+_encatch.identifyUser('user-123', userTraits);
 
-# Preview production build
-pnpm preview
+// Example with multiple operations
+const userTraitsAdvanced: UserTraits = {
+  $set: { email: 'user@example.com', name: 'John Doe' },
+  $setOnce: { firstSeenAt: new Date() },
+  $increment: { loginCount: 1 },
+  $unset: ['oldField'],
+};
 ```
 
-### Project Structure
+## How It Works
 
-```
-packages/web-sdk/
-├── src/
-│   ├── @types/          # TypeScript type definitions
-│   ├── hooks/           # Preact hooks for functionality
-│   ├── utils/           # Utility functions
-│   ├── index.tsx        # Main SDK initialization
-│   ├── core-wrapper.tsx # Core SDK logic
-│   └── surveySDK.ts     # Event SDK
-├── dist-sdk/            # Build output
-├── package.json
-├── vite.config.ts       # Vite configuration
-└── README.md
-```
-
-### Build Output
+The SDK uses a "stub + async loader" pattern:
 
-The build produces:
+1. The lightweight stub is loaded immediately and exposes the `_encatch` object
+2. All method calls are queued in an internal array
+3. When `init()` is called, the full implementation script is loaded from the CDN
+4. Once loaded, the queued commands are processed in order
+5. Future calls go directly to the real implementation
 
-- `encatch-web-sdk.js` - Main SDK bundle
-- `encatch-web-sdk.css` - Default styles
-- `preview-sdk.js` - Preview/demo version
-- `embedded-sdk.js` - Embedded version
+This pattern ensures:
+- Fast initial page load (tiny stub)
+- No lost commands (queue preserves all calls)
+- Type safety (full TypeScript definitions)
 
 ## Browser Support
 
-- Chrome 62+
-- Firefox 59+
-- Safari 12+
-- iOS Safari 10.3+
-- Opera 50+
-- Edge (Chromium-based)
+- Chrome 80+
+- Firefox 75+
+- Safari 13.1+
+- Edge 80+
 
 ## License
 
-Private - Copyright (c) Encatch
-
-## Support
-
-For issues, questions, or feature requests, please contact your Encatch account manager or visit the [Encatch Dashboard](https://app.encatch.com).
+MIT