@encatch/web-sdk 1.0.0 → 1.1.0-beta.0

package/README.md

@@ -1,18 +1,9 @@
 # @encatch/web-sdk
 
-A lightweight, type-safe JavaScript SDK for integrating Encatch forms and surveys into your web application.
-
-## Features
-
-- **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
+A lightweight, type-safe JavaScript SDK for integrating Encatch platform into your web application.
 
 ## Installation
 
-### NPM / Yarn / PNPM
-
 ```bash
 npm install @encatch/web-sdk
 # or
@@ -21,237 +12,11 @@ yarn add @encatch/web-sdk
 pnpm add @encatch/web-sdk
 ```
 
-### CDN / Script Tag
-
-```html
-<script src="https://unpkg.com/@encatch/web-sdk/dist/encatch.iife.js"></script>
-```
-
-## Quick Start
-
-### ES Modules
-
-```javascript
-import { _encatch } from '@encatch/web-sdk';
-
-// Initialize with your API key
-_encatch.init('YOUR_API_KEY');
-
-// Identify the user
-_encatch.identifyUser('user-123', {
-  email: 'user@example.com',
-  name: 'John Doe',
-});
-```
-
-### Script Tag
-
-```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, config?)`
-
-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', {
-  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')
-});
-```
-
-### `identifyUser(id, traits?, options?)`
-
-Identify the current user. The `id` is required, traits and options are optional.
-
-```javascript
-// 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)
-});
-
-// 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
-});
-```
-
-### `setLocale(locale)`
-
-Set the user's preferred language.
-
-```javascript
-_encatch.setLocale('fr,en,es'); // Comma-separated ISO 639-1 codes
-```
-
-### `setCountry(country)`
-
-Set the user's country.
-
-```javascript
-_encatch.setCountry('FR'); // ISO 3166 country code
-```
-
-### `setTheme(theme)`
-
-Set the theme. Default is 'system'.
-
-```javascript
-_encatch.setTheme('dark'); // 'light', 'dark', or 'system'
-_encatch.setTheme('light');
-_encatch.setTheme('system'); // Follows system preference
-```
-
-### `trackEvent(eventName)`
-
-Track a custom event.
-
-```javascript
-_encatch.trackEvent('button_clicked');
-_encatch.trackEvent('purchase_completed');
-```
-
-### `startSession()`
-
-Manually start a new session. Useful after user login.
-
-```javascript
-_encatch.startSession();
-```
-
-### `resetUser()`
-
-Reset the current user (logout). Reverts the SDK to anonymous mode.
-
-```javascript
-_encatch.resetUser();
-```
-
-### `showForm(formId, force?)`
-
-Show a specific form by ID.
-
-```javascript
-_encatch.showForm('form-abc-123');
-_encatch.showForm('form-abc-123', true); // Force show even if already shown
-```
-
-### `addToResponse(questionId, value)`
-
-Prepopulate a form response.
-
-```javascript
-_encatch.addToResponse('question-1', 'Pre-filled answer');
-```
-
-### `on(event, callback)`
-
-Subscribe to SDK events. Returns an unsubscribe function.
-
-```javascript
-const unsubscribe = _encatch.on('form:submit', (payload) => {
-  console.log('Form submitted:', payload);
-});
-
-// Later, to unsubscribe:
-unsubscribe();
-```
-
-### `off(event, callback)`
-
-Unsubscribe from SDK events.
-
-```javascript
-function handleSubmit(payload) {
-  console.log('Form submitted:', payload);
-}
-
-_encatch.on('form:submit', handleSubmit);
-
-// Later:
-_encatch.off('form:submit', handleSubmit);
-```
-
-## Event Types
-
-| 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 written in TypeScript and includes full type definitions.
-
-```typescript
-import { _encatch, UserTraits, EncatchConfig, EventType } from '@encatch/web-sdk';
-
-// Example with $set operation
-const userTraits: UserTraits = {
-  $set: {
-    email: 'user@example.com',
-    name: 'John Doe',
-    customField: 'value',
-  },
-};
-
-_encatch.identifyUser('user-123', userTraits);
-
-// Example with multiple operations
-const userTraitsAdvanced: UserTraits = {
-  $set: { email: 'user@example.com', name: 'John Doe' },
-  $setOnce: { firstSeenAt: new Date() },
-  $increment: { loginCount: 1 },
-  $unset: ['oldField'],
-};
-```
-
-## How It Works
-
-The SDK uses a "stub + async loader" pattern:
-
-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
-
-This pattern ensures:
-- Fast initial page load (tiny stub)
-- No lost commands (queue preserves all calls)
-- Type safety (full TypeScript definitions)
+## Documentation
 
-## Browser Support
+For the full API reference, configuration options, and usage examples, visit the official documentation:
 
-- Chrome 80+
-- Firefox 75+
-- Safari 13.1+
-- Edge 80+
+**[https://encatch.com/docs/sdk-reference/web](https://encatch.com/docs/sdk-reference/web)**
 
 ## License
 

package/dist/index.d.ts

@@ -3,6 +3,12 @@
  */
 declare type Command = [string, ...unknown[]];
 
+/**
+ * Context values that can be attached to a form submission.
+ * Date values are automatically serialized to ISO strings before being sent.
+ */
+declare type ContextValue = string | number | Date | boolean;
+
 declare const _encatch: EncatchSDK;
 export { _encatch }
 export default _encatch;
@@ -174,6 +180,12 @@ export declare interface ShowFormOptions {
      * @default 'always'
      */
     reset?: ResetMode;
+    /**
+     * Arbitrary key-value pairs attached to the form submission.
+     * Useful for passing caller-side metadata (e.g. plan tier, feature flag states).
+     * Date values are automatically serialized to ISO 8601 strings.
+     */
+    context?: Record<string, ContextValue>;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@encatch/web-sdk",
-  "version": "1.0.0",
+  "version": "1.1.0-beta.0",
   "description": "A lightweight, type-safe JavaScript SDK for integrating Encatch forms and surveys",
   "type": "module",
   "main": "dist/encatch.es.js",
@@ -40,8 +40,9 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/encatch/web-sdk"
+    "url": "https://github.com/get-encatch/web-sdk"
   },
+  "homepage": "https://encatch.com",
   "license": "MIT",
   "engines": {
     "node": ">=18"