@primexperts.co/pulse-agent 5.2.0 → 5.4.0

package/README.md

@@ -36,19 +36,52 @@ const agent = createPulseAgent({
 agent.open();
 ```
 
-## What You Need From Pulse
+## Why Teams Use Pulse Agent
 
-You need these values before going live:
+Pulse Agent is useful when a business has customer messages arriving through public-facing channels, but the team needs a controlled place to handle them.
 
-| Value | Example | Required | Where it comes from |
+Typical use cases:
+
+- A website visitor starts a chat and any available team member can respond from Pulse.
+- A support mailbox can be connected so the team manages customer email from a shared workspace instead of one person's inbox.
+- Conversation history stays attached to the customer interaction, so the next team member can continue with context.
+- Teams can separate customer communication by organization/application using the `slug` and `appKey`.
+- Website errors can be reported into Pulse so support and operations can see when customers are affected.
+
+The result is a team inbox model: one public channel for customers, multiple internal users for response and follow-up.
+
+## Channel Model
+
+| Channel | Current role | What the customer sees | What the team gets in Pulse |
 | --- | --- | --- | --- |
-| 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 |
+| Webchat | Supported through this package | Website chat launcher | Shared conversation thread, visitor profile, realtime replies, history, transcript action |
+| Email | Supported by Pulse integrations | Normal support email address | Shared email conversations in Pulse, independent of one person's mailbox |
+| 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 |
+
+## Self-Service Setup
+
+Pulse Agent is intended to be usable by any website owner who creates a Pulse workspace and enables Webchat.
 
-You usually do not need a widget token. The widget resolves it automatically by calling Pulse with your `slug` and `appKey`.
+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.
+
+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 |
@@ -261,7 +294,7 @@ onBeforeUnmount(() => agent?.destroy());
 At startup or first send, Pulse Agent calls:
 
 ```text
-GET /api/pulse/public/webchat/resolve?slug=<slug>&appKey=<app_...>
+GET /api/pulse/public/webchat/resolve?slug=<slug>[&appKey=<app_...>]
 ```
 
 Pulse returns the active widget configuration, including an internal `widgetToken`. The widget then uses that token for chat, history, streaming, transcript email, and error reporting.
@@ -324,7 +357,7 @@ Pulse Agent does not:
 The widget expects these Pulse endpoints:
 
 ```text
-GET  /api/pulse/public/webchat/resolve?slug=<slug>&appKey=<appKey>
+GET  /api/pulse/public/webchat/resolve?slug=<slug>[&appKey=<appKey>]
 POST /api/pulse/public/webchat/{widgetToken}/message
 GET  /api/pulse/public/webchat/{widgetToken}/messages?conversationId=<id>
 POST /api/pulse/public/webchat/{widgetToken}/transcript-email?conversationId=<id>
@@ -340,8 +373,10 @@ 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.
-- Supports visitor profile capture, history loading, transcript email requests, SSE replies, WhatsApp launcher, manual open/close, and manual exception reporting.
+- 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.
 
 ## Limitations
 
@@ -395,7 +430,7 @@ The public resolve endpoint is protected or the key is not accepted. Confirm the
 
 ### `Failed to resolve widget keys (404)`
 
-The slug is wrong, webchat is not enabled, or the selected application has no active widget.
+The slug is wrong, Webchat is not enabled, or the selected organization/application has no active widget.
 
 ### CORS error in the browser console
 
@@ -412,34 +447,4 @@ Confirm all of the following:
 - `errorMonitoring: true` is present in runtime config.
 - The widget successfully resolves a widget token.
 - The error happens after `createPulseAgent(...)` runs.
-- The browser can post to `/api/pulse/public/webchat/{widgetToken}/errors`.
-
-## Additional Documentation
-
-- `docs/IMPLEMENTATION-GUIDE.md` for end-to-end setup examples.
-- `docs/TROUBLESHOOTING.md` for diagnostics.
-- `docs/FAQ.md` for common questions.
-- `docs/INTEGRATION-CHANNELS.md` for channel-level implementation notes.
-
-## Build and Publish
-
-```bash
-npm run build
-npm publish --access public
-```
-
-Build output includes:
-
-- ESM and type declarations in `dist/`.
-- Browser global bundle in `dist/browser/pulse-agent.global.js`.
-
-## Versioning
-
-Use the built-in version script instead of editing package files manually:
-
-```bash
-npm run version:patch
-npm run version:minor
-npm run version:major
-npm run version:bump -- 1.2.3
-```
+- The browser can post to `/api/pulse/public/webchat/{widgetToken}/errors`.

package/docs/DEVELOPER.md

@@ -0,0 +1,42 @@
+# Pulse Agent Developer Notes
+
+This document is for maintainers of `@primexperts.co/pulse-agent`. It is not required for customers installing the widget.
+
+## Repository Documentation
+
+- `docs/IMPLEMENTATION-GUIDE.md` - end-to-end setup examples and deployment guidance.
+- `docs/TROUBLESHOOTING.md` - diagnostics for CORS, resolve failures, streaming, and monitoring.
+- `docs/FAQ.md` - common integration questions.
+- `docs/INTEGRATION-CHANNELS.md` - channel-level implementation notes.
+
+## Build
+
+```bash
+npm run build
+```
+
+Build output includes:
+
+- ESM and type declarations in `dist/`.
+- Browser global bundle in `dist/browser/pulse-agent.global.js`.
+
+## Publish
+
+```bash
+npm publish --access public
+```
+
+`prepublishOnly` runs the build before publishing.
+
+## Versioning
+
+Use the built-in version script instead of editing package files manually:
+
+```bash
+npm run version:patch
+npm run version:minor
+npm run version:major
+npm run version:bump -- 1.2.3
+```
+
+This updates both `package.json` and `package-lock.json` when the script is used.

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

@@ -1,6 +1,6 @@
 # Pulse Agent Implementation Guide
 
-This guide explains how to add Pulse Agent to a website, configure it from environment variables, enable browser error monitoring, and verify the integration before production release.
+This guide explains how to add Pulse Agent to a website, configure it from environment variables, enable browser error monitoring, and verify the integration before production release. It also explains the bigger product model: Pulse Agent is the website entry point into a shared Pulse workspace where multiple users can manage customer conversations from connected channels.
 
 ## 1. What Pulse Agent Does
 
@@ -12,23 +12,45 @@ Pulse Agent is a browser widget for public websites. It provides:
 - Conversation history loading.
 - Realtime replies through Server-Sent Events.
 - Optional transcript/follow-up email action.
-- Optional WhatsApp launcher.
+- Optional WhatsApp launcher/contact path where configured; full WhatsApp shared-inbox handling should be described only when enabled for that deployment.
 - Optional website error monitoring for browser exceptions and failed fetch calls.
 
 Installing the package only makes the code available. The widget and error monitoring start only after your app calls `createPulseAgent(...)` with valid configuration.
 
-## 2. Required Pulse Values
+## 1.1. Source-Verified Product Capabilities
+
+The Pulse source supports more than a website chat bubble:
+
+- Authenticated Pulse users can work from an Inbox.
+- Admins can assign or reassign conversations.
+- Agents are assignment-scoped in the current role model.
+- Team members can reply to conversations and add internal notes.
+- Conversations support status, priority, activity, tags, follow-ups, quotes, and customer profiles.
+- Dashboard views show open/pending conversations, team load, and error summaries.
+- Email integrations can connect an inbox through IMAPS polling and convert unread mail into Pulse conversations.
+- Webchat uses public visitor endpoints, rate limiting, history, and SSE streaming.
+- 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. 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. |
-| `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. Do not configure it unless Pulse explicitly provides a token for a special case.
+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.
 
 ## 3. Install
 
@@ -48,10 +70,10 @@ 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
 });
@@ -63,7 +85,7 @@ 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,
@@ -87,7 +109,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
@@ -111,10 +133,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,10 +175,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,
@@ -195,10 +217,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
@@ -235,7 +257,7 @@ Use the browser global bundle and call `window.PulseAgent.createPulseAgent(...)`
 Pulse Agent calls these public endpoints:
 
 ```text
-GET  /api/pulse/public/webchat/resolve?slug=<slug>&appKey=<appKey>
+GET  /api/pulse/public/webchat/resolve?slug=<slug>[&appKey=<appKey>]
 POST /api/pulse/public/webchat/{widgetToken}/message
 GET  /api/pulse/public/webchat/{widgetToken}/messages?conversationId=<id>
 POST /api/pulse/public/webchat/{widgetToken}/transcript-email?conversationId=<id>
@@ -270,7 +292,7 @@ These endpoints are public by design for website visitors. Admin setup endpoints
 ## 13. Verification Checklist
 
 1. Open the site and confirm the Pulse launcher appears.
-2. In browser dev tools, confirm `resolve?slug=...&appKey=...` succeeds.
+2. In browser dev tools, confirm `resolve?slug=...` succeeds; if your deployment uses app keys, confirm `appKey=...` is included.
 3. Send a test message and confirm `message` succeeds.
 4. Confirm `stream` is open and receives replies.
 5. If history is enabled, confirm `messages?conversationId=...` succeeds.

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,40 +1,40 @@
-{
-    "name": "@primexperts.co/pulse-agent",
-    "version": "5.2.0",
-    "description": "Embeddable Pulse floating chat agent widget.",
-    "type": "module",
-    "main": "./dist/index.js",
-    "types": "./dist/index.d.ts",
-    "exports": {
-        ".": {
-            "types": "./dist/index.d.ts",
-            "default": "./dist/index.js"
-        }
-    },
-    "files": [
-        "dist",
-        "docs",
-        "README.md",
-        "LICENSE"
-    ],
-    "scripts": {
-        "clean": "node -e \"if(require('fs').existsSync('dist')) require('fs').rmSync('dist',{recursive:true,force:true})\"",
-        "build:types": "tsc -p tsconfig.build.json",
-        "build:browser": "node scripts/build-browser-global.mjs",
-        "build": "npm run clean && npm run build:types && npm run build:browser",
-        "version:bump": "node scripts/bump-version.mjs",
-        "version:patch": "node scripts/bump-version.mjs patch",
-        "version:minor": "node scripts/bump-version.mjs minor",
-        "version:major": "node scripts/bump-version.mjs major",
-        "prepublishOnly": "npm run build"
-    },
-    "private": false,
-    "license": "MIT",
-    "author": "PrimExperts",
-    "dependencies": {
-        "tslib": "^2.8.1"
-    },
-    "devDependencies": {
-        "typescript": "~5.8.2"
-    }
-}
+{
+  "name": "@primexperts.co/pulse-agent",
+  "version": "5.4.0",
+  "description": "Embeddable Pulse floating chat agent widget.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "node -e \"if(require('fs').existsSync('dist')) require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build:types": "tsc -p tsconfig.build.json",
+    "build:browser": "node scripts/build-browser-global.mjs",
+    "build": "npm run clean && npm run build:types && npm run build:browser",
+    "version:bump": "node scripts/bump-version.mjs",
+    "version:patch": "node scripts/bump-version.mjs patch",
+    "version:minor": "node scripts/bump-version.mjs minor",
+    "version:major": "node scripts/bump-version.mjs major",
+    "prepublishOnly": "npm run build"
+  },
+  "private": false,
+  "license": "MIT",
+  "author": "PrimExperts",
+  "dependencies": {
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "typescript": "~5.8.2"
+  }
+}