@primexperts.co/pulse-agent 5.2.0 → 5.3.0

package/README.md

@@ -36,6 +36,29 @@ const agent = createPulseAgent({
 agent.open();
 ```
 
+## Why Teams Use Pulse Agent
+
+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.
+
+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 |
+| --- | --- | --- | --- |
+| 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 |
+
 ## What You Need From Pulse
 
 You need these values before going live:
@@ -261,7 +284,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 +347,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>
@@ -341,7 +364,9 @@ Admin setup endpoints are separate and should remain authenticated.
 - 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.
+- 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 +420,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 +437,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/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,38 @@ 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.
 
+## 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. Required Pulse Values
 
 | Value | Required | Example | Notes |
 | --- | --- | --- | --- |
 | `slug` | Yes | `vayakids` | Public organization slug. |
-| `appKey` | Recommended | `app_abc123...` | Public application key from Pulse Dashboard. |
+| `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`.
 
-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
 
@@ -235,7 +250,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 +285,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/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.3.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"
+  }
+}