@primexperts.co/pulse-agent 5.3.0 → 5.6.0

package/README.md

@@ -59,19 +59,29 @@ The result is a team inbox model: one public channel for customers, multiple int
 | WhatsApp | Planned/optional depending on deployment | WhatsApp contact path | Intended shared handling model when enabled; do not promise as active unless configured |
 | Error Monitoring | Supported through this package | No visible customer UI | Browser exceptions and failed request reports tied to the website/application |
 
-## What You Need From Pulse
+## Self-Service Setup
 
-You need these values before going live:
+Pulse Agent is intended to be usable by any website owner who creates a Pulse workspace and enables Webchat.
 
-| Value | Example | Required | Where it comes from |
-| --- | --- | --- | --- |
-| Organization slug | `vayakids` | Yes | Pulse organization/webchat setup |
-| Application key | `app_...` | Recommended | Pulse Dashboard application/webchat setup |
-| API base URL | `https://pulse.service.primexperts.co.za` | Yes | Pulse production API host |
-| Allowed website origin | `https://www.example.com` | Yes | Must be allowed by Pulse CORS/backend configuration |
+Before adding the code snippet, do this in Pulse:
+
+1. Create or sign in to your Pulse account.
+2. Create your organization or workspace.
+3. Create/select the application or website you want to connect.
+4. Enable the Webchat integration.
+5. Copy the generated setup values into your website environment/config.
+6. Add your website origin, for example `https://www.example.com`, to the allowed origins/CORS settings if your Pulse deployment exposes that setting.
 
-You usually do not need a widget token. The widget resolves it automatically by calling Pulse with your `slug` and `appKey`.
+Use these values in your widget config:
+
+| Value | Example | Required | How to get it |
+| --- | --- | --- | --- |
+| Organization slug | `acme-support` | Yes | Shown in Pulse for your organization/workspace. |
+| Application key | `app_...` | Recommended when available | Copy from your Pulse application/webchat setup. |
+| API base URL | `https://pulse.service.primexperts.co.za` | Yes | Use the API URL shown by your Pulse environment. |
+| Website origin | `https://www.example.com` | Required for production | Add the exact site origin where the widget will run. |
 
+You usually do not need a widget token. Pulse Agent resolves it automatically from your organization slug; when an application key is configured, the agent also sends it for app-aware deployments and reporting context.
 ## Configuration Keys
 
 | Option | Type | Default | Description |
@@ -148,6 +158,21 @@ heroku config:set PULSE_AGENT_CAPTURE_FETCH_ERRORS=true
 
 If your app uses a `runtime-config.js` file, make sure Heroku serves that file from environment values at request time or regenerates it during build/startup.
 
+## Required Code Structure
+
+Pulse Agent does not require a special framework architecture, but it does need one clear bootstrap point.
+
+Structure your app so `createPulseAgent(...)` runs:
+
+- once per page/app session;
+- only in the browser, never during server-side rendering;
+- as early as practical after runtime config is available;
+- before the user flows you want error monitoring to observe;
+- from a stable root entry point such as `main.ts`, `App.tsx`, a root layout client component, `onMounted`, or a script loaded after `/runtime-config.js`.
+
+Do not initialize Pulse Agent inside frequently re-rendered child components, route components that mount repeatedly, button click handlers, or server-only files. If the root component can unmount, keep the returned handle and call `agent.destroy()` during cleanup.
+
+For error monitoring, timing matters: errors that happen before `createPulseAgent(...)` runs cannot be captured by Pulse Agent. If you want broad coverage, load runtime config first and initialize Pulse Agent before bootstrapping the rest of the application where your framework allows it.
 ## Runtime Config Pattern
 
 A common production-safe pattern is to load `/runtime-config.js` before your app bundle:
@@ -297,6 +322,19 @@ Do not confuse these values:
 | `widgetToken` | Token generated by Pulse | Internal public webchat token used by endpoints | Usually leave unset. |
 | `slug` | human-readable slug | Identifies organization | Put in config/env. |
 
+## Network Access and Security Scanners
+
+Security scanners such as Socket may flag this package for network access. That is expected and intentional.
+
+Pulse Agent is a browser widget, so it uses standard browser networking APIs to provide its features:
+
+- `fetch` resolves the active widget configuration.
+- `fetch` sends visitor messages to Pulse.
+- `fetch` loads conversation history and sends transcript/error-report requests.
+- `EventSource` keeps the chat connected for realtime replies.
+- Optional `fetch` wrapping reports failed website requests only when `errorMonitoring` and `captureFetchErrors` are enabled.
+
+The package does not run install scripts, does not start background processes, does not open arbitrary sockets, and does not use Node filesystem or shell APIs at runtime. Network calls are made from the visitor's browser after the website initializes `createPulseAgent(...)`, and they target the configured `apiBaseUrl` plus optional WhatsApp links when configured.
 ## Error Monitoring
 
 Error monitoring is opt-in. Installing the package does not capture anything until `errorMonitoring: true` is passed to `createPulseAgent`.
@@ -363,7 +401,7 @@ Admin setup endpoints are separate and should remain authenticated.
 - Framework-agnostic browser integration.
 - Works with npm or a script tag.
 - Supports runtime configuration, which is useful for Heroku, Docker, static hosting, and multi-environment deployments.
-- Uses `slug` + `appKey` so users do not need to handle internal widget tokens.
+- Uses the organization `slug`, plus `appKey` when available, so users do not need to handle internal widget tokens.
 - Supports visitor profile capture, history loading, transcript email requests, SSE replies, WhatsApp launcher/contact path where configured, manual open/close, and manual exception reporting.
 - Supports operational workflows verified in the Pulse source: assignment, status/priority updates, internal notes, follow-ups, customer profiles, tags, notifications, activity logs, exports, and dashboard KPIs.
 - Supports role-based team operation: admins manage setup and assignment, while agents work assigned conversations.

package/docs/FAQ.md

@@ -15,7 +15,7 @@ Do not use dashboard host URLs as API base URLs.
 ## What slug should I use?
 
 Use the organization slug generated from organization name (lowercase, alphanumeric, hyphen-separated).  
-Example: `PrimeXperts` -> `primexperts`
+Example: `Acme Support` -> `acme-support`
 
 ## Do users need to log in to use the widget?
 

package/docs/IMPLEMENTATION-GUIDE.md

@@ -32,16 +32,23 @@ The Pulse source supports more than a website chat bubble:
 - Error monitoring can post browser error reports to Pulse and feed dashboard summaries.
 
 This is why the strongest positioning is: Pulse Agent gets the customer conversation or browser issue into Pulse; Pulse gives the team a controlled workspace to manage it together.
-## 2. Required Pulse Values
+## 2. Self-Service Pulse Setup
+
+Pulse Agent is intended for any website owner. Start in Pulse, then copy the values into your website config.
+
+1. Create or sign in to your Pulse account.
+2. Create your organization or workspace.
+3. Create/select the application or website you want to connect.
+4. Enable Webchat.
+5. Copy the generated slug and application key, when available.
+6. Add your website origin to the allowed origins/CORS settings if your Pulse environment exposes that setting.
 
 | Value | Required | Example | Notes |
 | --- | --- | --- | --- |
-| `slug` | Yes | `vayakids` | Public organization slug. |
-| `appKey` | Recommended | `app_abc123...` | Public application key from Pulse Dashboard. The agent sends it when present; app-aware Pulse deployments can use it for application separation and reporting context. |
-| `apiBaseUrl` | Yes | `https://pulse.service.primexperts.co.za` | Host only; do not add `/api`. |
-| Website origin | Yes | `https://app.example.com` | Must be allowed by Pulse CORS/backend configuration. |
-
-The `appKey` is the value that starts with `app_`. It is not the same as `widgetToken`.
+| `slug` | Yes | `acme-support` | Organization/workspace slug shown in Pulse. |
+| `appKey` | Recommended when available | `app_abc123...` | Application key copied from Pulse setup. The agent sends it when present for app-aware deployments and reporting context. |
+| `apiBaseUrl` | Yes | `https://pulse.service.primexperts.co.za` | Use the API URL shown by your Pulse environment. Do not add `/api`. |
+| Website origin | Production only | `https://app.example.com` | Exact site origin where the widget runs. |
 
 A `widgetToken` is normally resolved automatically by Pulse from the organization `slug`; when `appKey` is configured, the agent also sends it for app-aware deployments. Do not configure `widgetToken` unless Pulse explicitly provides a token for a special case.
 
@@ -63,22 +70,35 @@ For script-tag usage:
 import { createPulseAgent } from '@primexperts.co/pulse-agent';
 
 createPulseAgent({
-  slug: 'vayakids',
+  slug: 'acme-support',
   appKey: 'app_your_public_application_key',
   apiBaseUrl: 'https://pulse.service.primexperts.co.za',
-  title: 'VayaKids',
+  title: 'Acme Support',
   requireProfile: true,
   autoOpen: false
 });
 ```
 
+## Network Access and Security Scanners
+
+Security scanners such as Socket may flag this package for network access. That is expected and intentional.
+
+Pulse Agent is a browser widget, so it uses standard browser networking APIs to provide its features:
+
+- `fetch` resolves the active widget configuration.
+- `fetch` sends visitor messages to Pulse.
+- `fetch` loads conversation history and sends transcript/error-report requests.
+- `EventSource` keeps the chat connected for realtime replies.
+- Optional `fetch` wrapping reports failed website requests only when `errorMonitoring` and `captureFetchErrors` are enabled.
+
+The package does not run install scripts, does not start background processes, does not open arbitrary sockets, and does not use Node filesystem or shell APIs at runtime. Network calls are made from the visitor's browser after the website initializes `createPulseAgent(...)`, and they target the configured `apiBaseUrl` plus optional WhatsApp links when configured.
 ## 5. Error Monitoring Configuration
 
 Error monitoring is off by default. Enable it explicitly:
 
 ```ts
 createPulseAgent({
-  slug: 'vayakids',
+  slug: 'acme-support',
   appKey: 'app_your_public_application_key',
   apiBaseUrl: 'https://pulse.service.primexperts.co.za',
   errorMonitoring: true,
@@ -102,7 +122,7 @@ Manual capture:
 
 ```ts
 const agent = createPulseAgent({
-  slug: 'vayakids',
+  slug: 'acme-support',
   appKey: 'app_your_public_application_key',
   apiBaseUrl: 'https://pulse.service.primexperts.co.za',
   errorMonitoring: true
@@ -126,10 +146,10 @@ try {
 Use these names in Heroku, Docker, CI, or your hosting platform:
 
 ```env
-PULSE_AGENT_SLUG=vayakids
+PULSE_AGENT_SLUG=acme-support
 PULSE_AGENT_APP_KEY=app_your_public_application_key
 PULSE_AGENT_API_BASE_URL=https://pulse.service.primexperts.co.za
-PULSE_AGENT_TITLE=VayaKids
+PULSE_AGENT_TITLE=Acme Support
 PULSE_AGENT_ENVIRONMENT=production
 PULSE_AGENT_RELEASE=web-1.0.0
 
@@ -153,6 +173,21 @@ PULSE_AGENT_WIDGET_TOKEN=
 
 Leave `PULSE_AGENT_WIDGET_TOKEN` empty unless Pulse tells you to use it.
 
+## Required Code Structure
+
+Pulse Agent does not require a special framework architecture, but it does need one clear bootstrap point.
+
+Structure your app so `createPulseAgent(...)` runs:
+
+- once per page/app session;
+- only in the browser, never during server-side rendering;
+- as early as practical after runtime config is available;
+- before the user flows you want error monitoring to observe;
+- from a stable root entry point such as `main.ts`, `App.tsx`, a root layout client component, `onMounted`, or a script loaded after `/runtime-config.js`.
+
+Do not initialize Pulse Agent inside frequently re-rendered child components, route components that mount repeatedly, button click handlers, or server-only files. If the root component can unmount, keep the returned handle and call `agent.destroy()` during cleanup.
+
+For error monitoring, timing matters: errors that happen before `createPulseAgent(...)` runs cannot be captured by Pulse Agent. If you want broad coverage, load runtime config first and initialize Pulse Agent before bootstrapping the rest of the application where your framework allows it.
 ## 7. Runtime Config Setup
 
 Frontend bundles usually cannot read platform environment variables directly at runtime. Use a runtime config file generated from environment variables.
@@ -168,10 +203,10 @@ Example `runtime-config.js` output:
 ```js
 window.__APP_RUNTIME_CONFIG__ = {
   pulseAgent: {
-    slug: 'vayakids',
+    slug: 'acme-support',
     appKey: 'app_your_public_application_key',
     apiBaseUrl: 'https://pulse.service.primexperts.co.za',
-    title: 'VayaKids',
+    title: 'Acme Support',
     errorMonitoring: true,
     captureUnhandledErrors: true,
     captureUnhandledRejections: true,
@@ -210,10 +245,10 @@ if (pulseAgentConfig?.slug) {
 Set config vars:
 
 ```bash
-heroku config:set PULSE_AGENT_SLUG=vayakids
+heroku config:set PULSE_AGENT_SLUG=acme-support
 heroku config:set PULSE_AGENT_APP_KEY=app_your_public_application_key
 heroku config:set PULSE_AGENT_API_BASE_URL=https://pulse.service.primexperts.co.za
-heroku config:set PULSE_AGENT_TITLE=VayaKids
+heroku config:set PULSE_AGENT_TITLE=Acme Support
 heroku config:set PULSE_AGENT_ENVIRONMENT=production
 heroku config:set PULSE_AGENT_ERROR_MONITORING=true
 heroku config:set PULSE_AGENT_CAPTURE_UNHANDLED_ERRORS=true

package/docs/INTEGRATION-CHANNELS.md

@@ -47,7 +47,7 @@ This guide documents how to integrate Pulse by channel type and which technologi
 import { createPulseAgent } from '@primexperts.co/pulse-agent';
 
 createPulseAgent({
-  slug: 'primexperts',
+  slug: 'acme-support',
   apiBaseUrl: 'https://pulse.service.primexperts.co.za',
   requireProfile: true
 });

package/docs/TROUBLESHOOTING.md

@@ -71,11 +71,11 @@ regexp_replace(
 ```
 
 Then:
-- `PrimeXperts` -> `primexperts`
+- `Acme Support` -> `acme-support`
 
 Resolve URL:
 
-`https://pulse.service.primexperts.co.za/api/pulse/public/webchat/resolve?slug=primexperts`
+`https://pulse.service.primexperts.co.za/api/pulse/public/webchat/resolve?slug=acme-support`
 
 ## 8) Quick verification checklist
 

package/package.json

@@ -1,18 +1,28 @@
 {
   "name": "@primexperts.co/pulse-agent",
-  "version": "5.3.0",
+  "version": "5.6.0",
   "description": "Embeddable Pulse floating chat agent widget.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./browser": "./dist/browser/pulse-agent.global.js"
   },
   "files": [
-    "dist",
+    "dist/index.js",
+    "dist/index.js.map",
+    "dist/index.d.ts",
+    "dist/index.d.ts.map",
+    "dist/widget",
+    "dist/browser/pulse-agent.global.js",
     "docs",
     "README.md",
     "LICENSE"
@@ -31,9 +41,7 @@
   "private": false,
   "license": "MIT",
   "author": "PrimExperts",
-  "dependencies": {
-    "tslib": "^2.8.1"
-  },
+  "dependencies": {},
   "devDependencies": {
     "typescript": "~5.8.2"
   }