npm - @active-reach/web-sdk - Versions diffs - 1.0.0 - Mend

@active-reach/web-sdk 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (80) hide show

package/README.md +576 -0
package/dist/aegis-sw.js +1 -0
package/dist/aegis.min.js +2 -0
package/dist/aegis.min.js.map +1 -0
package/dist/analytics-B11keZ55.mjs +1854 -0
package/dist/analytics-B11keZ55.mjs.map +1 -0
package/dist/cdn.d.ts +18 -0
package/dist/cdn.d.ts.map +1 -0
package/dist/core/analytics.d.ts +47 -0
package/dist/core/analytics.d.ts.map +1 -0
package/dist/core/queue.d.ts +35 -0
package/dist/core/queue.d.ts.map +1 -0
package/dist/core/sdk-config-poller.d.ts +59 -0
package/dist/core/sdk-config-poller.d.ts.map +1 -0
package/dist/core/session.d.ts +41 -0
package/dist/core/session.d.ts.map +1 -0
package/dist/core/transport.d.ts +50 -0
package/dist/core/transport.d.ts.map +1 -0
package/dist/inapp/AegisInAppManager.d.ts +126 -0
package/dist/inapp/AegisInAppManager.d.ts.map +1 -0
package/dist/inapp/index.d.ts +4 -0
package/dist/inapp/index.d.ts.map +1 -0
package/dist/inapp/renderPreview.d.ts +25 -0
package/dist/inapp/renderPreview.d.ts.map +1 -0
package/dist/index.d.ts +23 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +4296 -0
package/dist/index.js.map +1 -0
package/dist/integrations/react.d.ts +19 -0
package/dist/integrations/react.d.ts.map +1 -0
package/dist/placements/AegisPlacementManager.d.ts +88 -0
package/dist/placements/AegisPlacementManager.d.ts.map +1 -0
package/dist/plugins/registry.d.ts +13 -0
package/dist/plugins/registry.d.ts.map +1 -0
package/dist/push/AegisWebPush.d.ts +51 -0
package/dist/push/AegisWebPush.d.ts.map +1 -0
package/dist/push/AegisWebPush.js +203 -0
package/dist/push/AegisWebPush.js.map +1 -0
package/dist/react.js +70 -0
package/dist/react.js.map +1 -0
package/dist/snippet.min.js +1 -0
package/dist/triggers/TriggerEngine.d.ts +114 -0
package/dist/triggers/TriggerEngine.d.ts.map +1 -0
package/dist/triggers/index.d.ts +3 -0
package/dist/triggers/index.d.ts.map +1 -0
package/dist/types/config.d.ts +73 -0
package/dist/types/config.d.ts.map +1 -0
package/dist/types/events.d.ts +127 -0
package/dist/types/events.d.ts.map +1 -0
package/dist/types/index.d.ts +5 -0
package/dist/types/index.d.ts.map +1 -0
package/dist/types/plugin.d.ts +21 -0
package/dist/types/plugin.d.ts.map +1 -0
package/dist/types/type-safe-events.d.ts +14 -0
package/dist/types/type-safe-events.d.ts.map +1 -0
package/dist/utils/canonical-identity.d.ts +29 -0
package/dist/utils/canonical-identity.d.ts.map +1 -0
package/dist/utils/consent.d.ts +40 -0
package/dist/utils/consent.d.ts.map +1 -0
package/dist/utils/debounce.d.ts +3 -0
package/dist/utils/debounce.d.ts.map +1 -0
package/dist/utils/device.d.ts +6 -0
package/dist/utils/device.d.ts.map +1 -0
package/dist/utils/identity.d.ts +27 -0
package/dist/utils/identity.d.ts.map +1 -0
package/dist/utils/index.d.ts +7 -0
package/dist/utils/index.d.ts.map +1 -0
package/dist/utils/logger.d.ts +15 -0
package/dist/utils/logger.d.ts.map +1 -0
package/dist/utils/storage.d.ts +20 -0
package/dist/utils/storage.d.ts.map +1 -0
package/dist/utils/url-parser.d.ts +23 -0
package/dist/utils/url-parser.d.ts.map +1 -0
package/dist/utils/uuid.d.ts +4 -0
package/dist/utils/uuid.d.ts.map +1 -0
package/dist/widgets/AegisWidgetManager.d.ts +194 -0
package/dist/widgets/AegisWidgetManager.d.ts.map +1 -0
package/dist/widgets/index.d.ts +3 -0
package/dist/widgets/index.d.ts.map +1 -0
package/package.json +73 -0

package/README.md ADDED Viewed

@@ -0,0 +1,576 @@
+# @active-reach/web-sdk
+Web SDK for **Active Reach Intelligence** — lightweight event tracking, identity resolution, in-app messaging, web push, and inline content placements.
+**12KB gzipped** | **<1KB async loader** | **Zero impact on page load**
+---
+## Prerequisites
+Before integrating, you need:
+1. **Write Key** — Retrieve from your Active Reach Intelligence dashboard under **Settings > Developer > API Keys**.
+2. **API Host** — Your cell endpoint URL (provided during onboarding).
+> **Note:** The write key is a **publishable identifier** (like a Stripe publishable key). It is safe to include in client-side code. It can only send events — it cannot read data, modify configuration, or access other tenants. Never use your **Secret Key** in client-side code.
+---
+## Installation
+### NPM (Recommended)
+```bash
+npm install @active-reach/web-sdk
+```
+### CDN (Async Loader)
+Add this snippet to your `<head>` tag. The async loader queues all calls until the full SDK loads — zero blocking.
+```html
+<script>
+  !function(){var e=window.aegis=window.aegis||[];if(!e.invoked){e.invoked=!0,e.methods=["init","track","identify","page","group","alias","reset","flush","use","debug","setCell","getCellInfo","getAnonymousId","getUserId","getSessionId","setConsent","grantConsent","denyConsent","hasConsent","getConsentPreferences","onConsentChange"],e.factory=function(t){return function(){var n=Array.prototype.slice.call(arguments);return n.unshift(t),e.push(n),e}};for(var t=0;t<e.methods.length;t++){var n=e.methods[t];e[n]=e.factory(n)}e.load=function(t,n){var o=document.createElement("script");o.type="text/javascript",o.async=!0,o.src=n&&n.cdnUrl?n.cdnUrl:"https://cdn.activereach.ai/sdk/aegis.min.js",o.onerror=function(){window.console&&console.error("Aegis SDK failed to load")};var r=document.getElementsByTagName("script")[0];r.parentNode.insertBefore(o,r),e._loadOptions={key:t,options:n}},e.SNIPPET_VERSION="1.0.0"}}();
+  aegis.load('YOUR_WRITE_KEY');
+  aegis.init('YOUR_WRITE_KEY', {
+    api_host: 'https://YOUR_CELL.activereach.ai'
+  });
+</script>
+```
+---
+## Quick Start
+### NPM / ES Modules
+```typescript
+import aegis from '@active-reach/web-sdk';
+await aegis.init('YOUR_WRITE_KEY', {
+  api_host: 'https://YOUR_CELL.activereach.ai',
+  auto_page_view: true,
+});
+// Track an event
+aegis.track('Purchase Completed', {
+  order_id: 'ORD-123',
+  revenue: 99.99,
+  currency: 'INR',
+});
+// Identify a user
+aegis.identify('user_123', {
+  email: 'user@example.com',
+  name: 'Priya Sharma',
+  plan: 'premium',
+});
+```
+### React
+```tsx
+import { AegisProvider, useAegis, useTrackEvent } from '@active-reach/web-sdk/react';
+function App() {
+  return (
+    <AegisProvider
+      writeKey="YOUR_WRITE_KEY"
+      config={{ api_host: 'https://YOUR_CELL.activereach.ai', auto_page_view: true }}
+    >
+      <Dashboard />
+    </AegisProvider>
+  );
+}
+function Dashboard() {
+  const { isReady } = useAegis();
+  const trackEvent = useTrackEvent();
+  return (
+    <button onClick={() => trackEvent('Button Clicked', { button: 'CTA' })}>
+      Track Event
+    </button>
+  );
+}
+```
+### Next.js
+```tsx
+// app/providers.tsx
+'use client';
+import { AegisProvider } from '@active-reach/web-sdk/react';
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <AegisProvider
+      writeKey={process.env.NEXT_PUBLIC_AEGIS_WRITE_KEY!}
+      config={{ api_host: process.env.NEXT_PUBLIC_AEGIS_API_HOST! }}
+    >
+      {children}
+    </AegisProvider>
+  );
+}
+```
+---
+## Configuration
+```typescript
+await aegis.init('YOUR_WRITE_KEY', {
+  // Required
+  api_host: string;
+  // Batching & Performance
+  batch_size?: number;           // default: 10
+  batch_interval?: number;       // default: 1000ms
+  // Data Capture
+  capture_utm?: boolean;         // default: true
+  capture_referrer?: boolean;    // default: true
+  auto_page_view?: boolean;      // default: false
+  // Session
+  session_timeout?: number;      // default: 1800000 (30 min)
+  // Privacy & Consent
+  respect_dnt?: boolean;         // default: true
+  enable_consent_mode?: boolean; // default: false
+  wait_for_consent?: boolean;    // default: false
+  default_consent?: {
+    analytics?: boolean;         // default: false
+    marketing?: boolean;         // default: false
+    functional?: boolean;        // default: true
+  };
+  integrate_onetrust?: boolean;
+  integrate_cookiebot?: boolean;
+  integrate_google_consent_mode?: boolean;
+  // Cookie
+  cross_domain_tracking?: boolean; // default: false
+  cookie_domain?: string;
+  secure_cookie?: boolean;         // default: true
+  // Offline & Retry
+  enable_offline_mode?: boolean;   // default: true
+  max_offline_events?: number;     // default: 100
+  retry_failed_requests?: boolean; // default: true
+  max_retries?: number;            // default: 3
+  // Regional Cell Selection
+  cell_endpoints?: CellEndpoint[];
+  preferred_region?: string;
+  auto_region_detection?: boolean; // default: true
+  // Debug
+  debug?: boolean;                 // default: false
+});
+```
+---
+## Core API
+### `aegis.track(eventName, properties?)`
+Track a custom event.
+```typescript
+aegis.track('Product Viewed', {
+  product_id: 'SKU-12345',
+  product_name: 'Leather Jacket',
+  price: 199.99,
+  category: 'Outerwear',
+});
+```
+### `aegis.identify(userId, traits?)`
+Identify a user and associate traits.
+```typescript
+aegis.identify('user_123', {
+  email: 'user@example.com',
+  name: 'John Doe',
+  plan: 'premium',
+});
+```
+### `aegis.page(name?, properties?)`
+Track a page view.
+```typescript
+aegis.page('Product Page', { product_id: 'SKU-12345' });
+```
+### `aegis.group(groupId, traits?)`
+Associate a user with a group (company, organization).
+```typescript
+aegis.group('company_789', {
+  name: 'Acme Corp',
+  industry: 'Technology',
+  employees: 500,
+});
+```
+### `aegis.alias(newUserId)`
+Merge two user identities.
+```typescript
+aegis.alias('permanent_user_id');
+```
+### `aegis.reset()`
+Clear user identity on logout. Generates a new anonymous ID.
+```typescript
+aegis.reset();
+```
+### `aegis.flush()`
+Force-send all queued events immediately.
+```typescript
+await aegis.flush();
+```
+---
+## React Hooks
+Import from `@active-reach/web-sdk/react`:
+| Hook | Returns | Description |
+|------|---------|-------------|
+| `useAegis()` | `{ aegis, isReady }` | Access SDK instance and readiness state |
+| `useTrackEvent()` | `(name, props?) => void` | Memoized event tracking callback |
+| `usePageView(name?, props?, deps?)` | — | Track page views on mount/dependency change |
+| `useIdentifyUser()` | `(userId, traits?) => void` | Memoized identify callback |
+---
+## Consent Management
+Built-in support for GDPR/CCPA compliance.
+```typescript
+// Set preferences
+aegis.setConsent({ analytics: true, marketing: false, functional: true });
+// Grant / deny
+aegis.grantConsent();           // all categories
+aegis.grantConsent('analytics'); // specific category
+aegis.denyConsent();
+aegis.denyConsent('marketing');
+// Query
+aegis.hasConsent('analytics');   // boolean
+aegis.getConsentPreferences();   // full object
+// Listen for changes
+const unsubscribe = aegis.onConsentChange((prefs) => {
+  console.log('Consent updated:', prefs);
+});
+```
+### Third-Party Integrations
+```typescript
+// OneTrust
+aegis.init('KEY', { enable_consent_mode: true, integrate_onetrust: true });
+// Cookiebot
+aegis.init('KEY', { enable_consent_mode: true, integrate_cookiebot: true });
+// Google Consent Mode v2
+aegis.init('KEY', { enable_consent_mode: true, integrate_google_consent_mode: true });
+```
+---
+## Web Push Notifications
+Import from `@active-reach/web-sdk/push`:
+```typescript
+import { AegisWebPush } from '@active-reach/web-sdk/push';
+const push = new AegisWebPush({
+  writeKey: 'YOUR_WRITE_KEY',
+  apiHost: 'https://YOUR_CELL.activereach.ai',
+  vapidPublicKey: 'YOUR_VAPID_PUBLIC_KEY',
+  contactId: 'user_123',
+  organizationId: 'org_456',
+  serviceWorkerPath: '/aegis-sw.js',
+});
+await push.initialize();
+```
+Copy `dist/aegis-sw.js` to your `public/` directory so the service worker is served at the root.
+---
+## In-App Messaging
+```typescript
+import { AegisInAppManager } from '@active-reach/web-sdk';
+const inApp = new AegisInAppManager({
+  writeKey: 'YOUR_WRITE_KEY',
+  apiHost: 'https://YOUR_CELL.activereach.ai',
+  contactId: 'user_123',
+  organizationId: 'org_456',
+});
+await inApp.initialize();
+```
+Campaign display rules (modal, banner, tooltip, slide-in) are configured server-side. The SDK evaluates client-side triggers (scroll depth, time on page, exit intent, inactivity) and renders campaigns automatically.
+---
+## Inline Content Placements
+```typescript
+import { AegisPlacementManager } from '@active-reach/web-sdk';
+const placements = new AegisPlacementManager({
+  writeKey: 'YOUR_WRITE_KEY',
+  apiHost: 'https://YOUR_CELL.activereach.ai',
+  contactId: 'user_123',
+  organizationId: 'org_456',
+  enableSSE: true,
+});
+await placements.initialize();
+// Register a slot in your page
+placements.registerSlot({
+  placementId: 'homepage_hero',
+  containerId: 'aegis-hero-slot',
+  fallbackContent: '<p>Loading...</p>',
+});
+```
+Placements support banner, card, carousel, video, and HTML content types. Content is managed server-side and delivered via SSE for real-time updates.
+> **HTML Placements:** For full HTML content rendering, add [DOMPurify](https://github.com/cure53/DOMPurify) to your page. Without it, HTML placements fall back to text-only rendering.
+>
+> ```html
+> <script src="https://cdnjs.cloudflare.com/ajax/libs/dompurify/3.2.4/purify.min.js"></script>
+> ```
+---
+## Widgets (Exit Intent, Surveys, Gamification)
+```typescript
+import { AegisWidgetManager, TriggerEngine } from '@active-reach/web-sdk';
+const triggerEngine = new TriggerEngine();
+const widgets = new AegisWidgetManager({
+  writeKey: 'YOUR_WRITE_KEY',
+  apiHost: 'https://YOUR_CELL.activereach.ai',
+  contactId: 'user_123',
+  organizationId: 'org_456',
+  triggerEngine,
+  enablePrefetch: true,
+});
+await widgets.initialize();
+```
+### Cart Recovery (Platform Auto-Detection)
+The SDK auto-detects cart data from:
+| Platform | Detection Method | Setup |
+|----------|-----------------|-------|
+| **Shopify** | `window.Shopify.checkout` / DOM `#cart-json` | None |
+| **WooCommerce** | `window.aegis_cart` (injected by plugin) | Install WP plugin |
+| **Magento 2** | `localStorage['mage-cache-storage']` | None |
+| **Custom / Mobile** | Manual via `setCartData()` | Required |
+```typescript
+// For custom platforms only
+widgets.setCartData({
+  cart_id: 'cart_123',
+  cart_total: 149.99,
+  cart_currency: 'INR',
+  cart_items: [
+    { product_id: 'prod_456', product_name: 'Premium Widget', quantity: 2, price: 74.99 }
+  ],
+});
+```
+---
+## Plugin System
+Extend the SDK with custom plugins:
+```typescript
+import type { Plugin } from '@active-reach/web-sdk';
+const myPlugin: Plugin = {
+  name: 'my-plugin',
+  version: '1.0.0',
+  async init(config) { /* called on SDK init */ },
+  async beforeEventCapture(event) {
+    // Modify or enrich events before capture
+    event.properties = { ...event.properties, enriched: true };
+    return event;
+  },
+  async afterEventCapture(event) {
+    // Post-capture logic (external forwarding, logging, etc.)
+  },
+};
+aegis.use(myPlugin);
+```
+---
+## TypeScript Support
+Full type definitions included. Extend for type-safe event tracking:
+```typescript
+// types/aegis.d.ts
+import '@active-reach/web-sdk';
+declare module '@active-reach/web-sdk' {
+  interface TrackEventProperties {
+    'Purchase Completed': {
+      order_id: string;
+      revenue: number;
+      currency: string;
+    };
+    'Product Viewed': {
+      product_id: string;
+      product_name: string;
+      price: number;
+    };
+  }
+}
+```
+---
+## Cookies & Storage
+| Name | Type | Purpose | Duration |
+|------|------|---------|----------|
+| `aegis_anon_id` | Cookie | Anonymous user identifier | 365 days |
+| `aegis_user_id` | Cookie | Identified user ID | 365 days |
+| `aegis_session_id` | Cookie | Current session ID | Session |
+| `aegis_session_time` | Cookie | Last activity timestamp | Session |
+| `aegis_consent` | Cookie | Consent preferences | 365 days |
+| `aegis_offline_queue` | localStorage | Offline event queue | Persistent |
+| `aegis_active_cell` | localStorage | Active regional cell | 7 days |
+All cookies: `SameSite=Lax`, `Secure` (HTTPS only), domain-scoped (optional).
+---
+## Content Security Policy (CSP)
+If your site uses a Content Security Policy, add these directives:
+```
+script-src: 'self' https://cdn.activereach.ai;
+connect-src: 'self' https://*.activereach.ai;
+style-src: 'self' 'unsafe-inline';
+img-src: 'self' https://*.activereach.ai data:;
+```
+If using DOMPurify via CDN, also add:
+```
+script-src: https://cdnjs.cloudflare.com;
+```
+**Common error when CSP is missing:** `Refused to connect to 'https://...activereach.ai'` — add the domain to `connect-src`.
+---
+## Security
+- **Write Key**: Publishable client-side identifier. Cannot read data or modify server state. Safe to embed in source code.
+- **HTML Sanitization**: Uses [DOMPurify](https://github.com/cure53/DOMPurify) when available with a strict allowlist. Falls back to text-only rendering.
+- **URL Validation**: All URLs validated — `javascript:` and `data:` protocols blocked.
+- **Consent**: Events are dropped (not queued) when consent is denied and `wait_for_consent` is enabled.
+- **Transport**: All API calls use HTTPS with bearer token authentication.
+### What NOT to track
+Never pass sensitive data as event properties:
+```typescript
+// Never do this
+aegis.track('Login', { password: '...' });
+aegis.identify('user_123', { ssn: '...', credit_card: '...' });
+```
+The SDK does not filter or redact properties. You are responsible for ensuring no PII beyond what you intend to collect is included in event payloads.
+---
+## Debugging
+```typescript
+aegis.debug(true);
+// Or via init
+aegis.init('KEY', { debug: true });
+```
+Console output:
+```
+[Aegis] Initializing SDK...
+[Aegis] Event queued: track { button_name: 'Sign Up' }
+[Aegis] Flushing 5 events
+[Aegis] Batch sent successfully
+```
+---
+## Subpath Exports
+| Import Path | Description |
+|-------------|-------------|
+| `@active-reach/web-sdk` | Core SDK (track, identify, page, group, alias) |
+| `@active-reach/web-sdk/react` | React Provider + hooks |
+| `@active-reach/web-sdk/push` | Web Push notification manager |
+| `@active-reach/web-sdk/cdn` | IIFE bundle for `<script>` tag (window.aegis) |
+| `@active-reach/web-sdk/snippet` | Minified async loader snippet |
+| `@active-reach/web-sdk/service-worker` | Push notification service worker |
+---
+## Browser Support
+Chrome 80+, Firefox 78+, Safari 14+, Edge 80+.
+---
+## License
+MIT

package/dist/aegis-sw.js ADDED Viewed

@@ -0,0 +1 @@

+ !function(){"use strict";function i(i){self.clients.matchAll({type:"window",includeUncontrolled:!0}).then(t=>{for(const n of t)n.postMessage(i)}).catch(()=>{})}self.addEventListener("push",t=>{if(!t.data)return;let n;try{n=t.data.json()}catch{n={title:t.data.text()||"Notification"}}const a=n.title||"Notification",e={body:n.body||"",icon:n.icon||void 0,badge:n.badge||void 0,image:n.image||void 0,tag:n.tag||n.campaign_id||void 0,data:{campaign_id:n.campaign_id,action_url:n.action_url||n.url,timestamp:Date.now()},actions:Array.isArray(n.actions)?n.actions.slice(0,2):[],requireInteraction:n.require_interaction??!1};t.waitUntil(self.registration.showNotification(a,e).then(()=>{i({type:"push.delivered",campaign_id:n.campaign_id})}))}),self.addEventListener("notificationclick",t=>{t.notification.close();const n=t.notification.data||{},a=n.action_url||"/";let e=a;if(t.action&&Array.isArray(t.notification.actions)){if(t.notification.actions.find(i=>i.action===t.action)){const i=n.action_urls||{};e=i[t.action]||a}}i({type:"push.clicked",campaign_id:n.campaign_id,action_url:e,action:t.action||"default"}),t.waitUntil(self.clients.matchAll({type:"window",includeUncontrolled:!0}).then(i=>{for(const t of i)if(new URL(t.url).origin===self.location.origin)return t.focus(),void t.navigate(e);return self.clients.openWindow(e)}))}),self.addEventListener("notificationclose",t=>{i({type:"push.dismissed",campaign_id:(t.notification.data||{}).campaign_id})}),self.addEventListener("pushsubscriptionchange",t=>{var n,a;t.waitUntil(self.registration.pushManager.subscribe({userVisibleOnly:!0,applicationServerKey:(null==(a=null==(n=t.oldSubscription)?void 0:n.options)?void 0:a.applicationServerKey)||void 0}).then(t=>{i({type:"push.resubscribed",subscription:t.toJSON()})}).catch(i=>{console.error("[aegis-sw] Failed to resubscribe:",i)}))})}();