@primexperts.co/pulse-agent 5.1.0 → 5.3.0

package/README.md

@@ -1,97 +1,440 @@
 # @primexperts.co/pulse-agent
 
-Embeddable floating Pulse chat widget for client websites.
+Pulse Agent is a browser-only customer support widget for adding Pulse Webchat and optional website error reporting to any public website, SPA, or client-rendered application.
 
-## Documentation
+It is designed for teams that want one lightweight install to do two jobs:
 
-- Adds a floating webchat launcher to any browser-based website or SPA.
-- Resolves the active Pulse webchat configuration by organization slug.
-- Sends visitor messages over public REST endpoints and receives agent replies over Server-Sent Events.
-- Supports optional pre-chat profile capture, conversation history loading, transcript email requests, and manual open/close controls.
-- Works with Angular, React, Vue, Next.js/Nuxt client components, static sites, and plain browser JavaScript.
+- Add a floating Pulse chat launcher to a website.
+- Report browser errors and failed API calls back to Pulse when error monitoring is enabled.
 
-## Install
+The package is framework-agnostic. It works with Angular, React, Vue, static HTML, and SSR frameworks when initialized on the client side.
+
+## Quick Start
 
 ```bash
-npm install '@primexperts.co/pulse-agent@latest'
+npm install @primexperts.co/pulse-agent@latest
 ```
 
-## Usage
-
 ```ts
 import { createPulseAgent } from '@primexperts.co/pulse-agent';
 
 const agent = createPulseAgent({
-  slug: 'client-abc',
+  slug: 'your-organization-slug',
+  appKey: 'app_your_public_application_key',
   apiBaseUrl: 'https://pulse.service.primexperts.co.za',
+  title: 'Support',
   requireProfile: true,
-  autoOpen: false
+  autoOpen: false,
+  errorMonitoring: true,
+  captureUnhandledErrors: true,
+  captureUnhandledRejections: true,
+  captureFetchErrors: true,
+  environment: 'production',
+  release: 'web-1.0.0'
 });
 
-// optional
 agent.open();
 ```
 
-## Browser/CDN Usage (No Bundler)
+## 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:
+
+| 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 |
+
+You usually do not need a widget token. The widget resolves it automatically by calling Pulse with your `slug` and `appKey`.
+
+## Configuration Keys
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `slug` | `string` | Required | Public organization slug used to resolve the active webchat widget. |
+| `appKey` | `string` | Optional but recommended | Public application key, normally starts with `app_`. Use this for application-specific setup and error attribution. |
+| `appSlug` | `string` | Optional | Alternative application identifier when an app key is not available. |
+| `apiBaseUrl` | `string` | `https://pulse.service.primexperts.co.za` | Pulse API host only. Do not include `/api/...` paths. |
+| `title` | `string` | Organization/app name | Chat panel title. |
+| `mount` | `HTMLElement \| string` | `document.body` | Element or selector where the widget root should be mounted. |
+| `autoOpen` | `boolean` | `false` | Opens the chat panel immediately after initialization. |
+| `requireProfile` | `boolean` | `true` | Requires visitor name/email before first message. |
+| `followUpEmailTo` | `string` | Optional | Destination used by transcript/follow-up email actions. |
+| `dashboardUrl` | `string` | `https://pulse.primexperts.co.za` | Dashboard link used in setup/error states. |
+| `dashboardSetupPath` | `string` | `/integrations` | Dashboard path linked when setup is incomplete. |
+| `whatsappUrl` | `string` | Optional | Adds a WhatsApp launcher alongside Pulse Chat. |
+| `widgetToken` | `string` | Optional | Advanced bypass for resolve flow. Leave unset unless Pulse gives you a specific token. |
+| `errorMonitoring` | `boolean` | `false` | Enables browser error reporting. Must be `true` before any capture happens. |
+| `captureUnhandledErrors` | `boolean` | `true` when monitoring is enabled | Captures `window.onerror` events. |
+| `captureUnhandledRejections` | `boolean` | `true` when monitoring is enabled | Captures unhandled promise rejections. |
+| `captureFetchErrors` | `boolean` | `true` when monitoring is enabled | Wraps browser `fetch` to report failed requests and thrown network errors. |
+| `environment` | `string` | Optional | Environment label such as `production`, `staging`, or `development`. |
+| `release` | `string` | Optional | Application release/version label for error context. |
+
+## Environment Variables
+
+Pulse Agent itself receives JavaScript options. For deployed apps, put values in your platform environment and generate or serve a runtime config file that passes those values to `createPulseAgent`.
+
+Recommended names:
+
+```env
+PULSE_AGENT_SLUG=your-organization-slug
+PULSE_AGENT_APP_KEY=app_your_public_application_key
+PULSE_AGENT_API_BASE_URL=https://pulse.service.primexperts.co.za
+PULSE_AGENT_TITLE=Support
+PULSE_AGENT_ENVIRONMENT=production
+PULSE_AGENT_RELEASE=web-1.0.0
+
+PULSE_AGENT_ERROR_MONITORING=true
+PULSE_AGENT_CAPTURE_UNHANDLED_ERRORS=true
+PULSE_AGENT_CAPTURE_UNHANDLED_REJECTIONS=true
+PULSE_AGENT_CAPTURE_FETCH_ERRORS=true
+```
+
+Optional names:
+
+```env
+PULSE_AGENT_FOLLOW_UP_EMAIL_TO=support@example.com
+PULSE_AGENT_DASHBOARD_URL=https://pulse.primexperts.co.za
+PULSE_AGENT_DASHBOARD_SETUP_PATH=/integrations
+PULSE_AGENT_AUTO_OPEN=false
+PULSE_AGENT_REQUIRE_PROFILE=true
+PULSE_AGENT_WHATSAPP_URL=https://api.whatsapp.com/send?phone=27123456789
+PULSE_AGENT_WIDGET_TOKEN=
+```
+
+Leave `PULSE_AGENT_WIDGET_TOKEN` unset unless Pulse Support explicitly gives you one. It is not the `app_*` key.
+
+## Heroku Config Vars
+
+Set these in Heroku under Settings -> Config Vars, or with the Heroku CLI:
+
+```bash
+heroku config:set PULSE_AGENT_SLUG=your-organization-slug
+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=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
+heroku config:set PULSE_AGENT_CAPTURE_UNHANDLED_REJECTIONS=true
+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.
+
+## Runtime Config Pattern
+
+A common production-safe pattern is to load `/runtime-config.js` before your app bundle:
+
+```html
+<script src="/runtime-config.js"></script>
+```
+
+Example generated file:
+
+```js
+window.__APP_RUNTIME_CONFIG__ = {
+  pulseAgent: {
+    slug: 'your-organization-slug',
+    appKey: 'app_your_public_application_key',
+    apiBaseUrl: 'https://pulse.service.primexperts.co.za',
+    title: 'Support',
+    errorMonitoring: true,
+    captureUnhandledErrors: true,
+    captureUnhandledRejections: true,
+    captureFetchErrors: true,
+    environment: 'production'
+  }
+};
+```
+
+Then initialize in your app entry point:
+
+```ts
+import { createPulseAgent, type PulseAgentOptions } from '@primexperts.co/pulse-agent';
+
+declare global {
+  interface Window {
+    __APP_RUNTIME_CONFIG__?: {
+      pulseAgent?: Partial<PulseAgentOptions>;
+    };
+  }
+}
+
+const config = window.__APP_RUNTIME_CONFIG__?.pulseAgent;
+
+if (config?.slug) {
+  createPulseAgent({
+    ...config,
+    slug: config.slug
+  });
+}
+```
+
+## Browser/CDN Usage
+
+Use this when you cannot install npm packages:
 
 ```html
 <script src="https://unpkg.com/@primexperts.co/pulse-agent@latest/dist/browser/pulse-agent.global.js"></script>
 <script>
-  const agent = window.PulseAgent.createPulseAgent({
-    slug: 'client-abc',
-    apiBaseUrl: 'https://pulse.service.primexperts.co.za'
+  window.PulseAgent.createPulseAgent({
+    slug: 'your-organization-slug',
+    appKey: 'app_your_public_application_key',
+    apiBaseUrl: 'https://pulse.service.primexperts.co.za',
+    title: 'Support',
+    errorMonitoring: true
   });
 </script>
 ```
 
-## Required Backend Endpoints
+## Framework Examples
+
+### Angular
+
+Initialize in `main.ts` or a browser-only root component. For SSR, guard against server execution.
 
-- `GET /api/pulse/public/webchat/resolve?slug=<slug>`
-- `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>`
-- `GET /api/pulse/public/webchat/{widgetToken}/stream?conversationId=<id>`
+```ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { createPulseAgent } from '@primexperts.co/pulse-agent';
+import { AppComponent } from './app/app.component';
 
-## API
+if (typeof window !== 'undefined') {
+  createPulseAgent({
+    slug: 'your-organization-slug',
+    appKey: 'app_your_public_application_key',
+    apiBaseUrl: 'https://pulse.service.primexperts.co.za',
+    errorMonitoring: true
+  });
+}
 
-### `createPulseAgent(options)`
+bootstrapApplication(AppComponent);
+```
 
-Options:
-- `slug` (required): public organization slug.
-- `apiBaseUrl` (optional): defaults to `https://pulse.service.primexperts.co.za`.
-- `followUpEmailTo` (optional): preferred destination for transcript follow-up emails.
-- `mount` (optional): container element or selector, defaults to `document.body`.
-- `autoOpen` (optional): open panel immediately.
-- `requireProfile` (optional): requires name/email before first message, default `true`.
-- `widgetToken` (optional): bypass slug resolution.
-- `title` (optional): panel title.
+### React
 
-Returns `PulseAgentHandle`:
-- `open()`
-- `close()`
-- `destroy()`
-- `update(partialOptions)`
+```tsx
+import { useEffect } from 'react';
+import { createPulseAgent } from '@primexperts.co/pulse-agent';
 
-## Notes
+export function PulseAgentBootstrap() {
+  useEffect(() => {
+    const agent = createPulseAgent({
+      slug: 'your-organization-slug',
+      appKey: 'app_your_public_application_key',
+      apiBaseUrl: 'https://pulse.service.primexperts.co.za',
+      errorMonitoring: true
+    });
 
-- This package is framework-agnostic and browser-only.
-- No dashboard/auth code is included in this project.
-- If widget keys cannot be resolved, the chat shows an error message and retries resolution on the next send attempt.
-- `npm run build` now outputs:
-  - ESM + type declarations in `dist/`
-  - browser global bundle in `dist/browser/pulse-agent.global.js`
+    return () => agent.destroy();
+  }, []);
 
-## Versioning
+  return null;
+}
+```
 
-Use the built-in version script instead of editing files manually:
+### Vue
 
-```bash
-npm run version:patch
-# or
-npm run version:minor
-npm run version:major
-# or custom semver
-npm run version:bump -- 1.2.3
+```ts
+import { onBeforeUnmount, onMounted } from 'vue';
+import { createPulseAgent, type PulseAgentHandle } from '@primexperts.co/pulse-agent';
+
+let agent: PulseAgentHandle | null = null;
+
+onMounted(() => {
+  agent = createPulseAgent({
+    slug: 'your-organization-slug',
+    appKey: 'app_your_public_application_key',
+    apiBaseUrl: 'https://pulse.service.primexperts.co.za',
+    errorMonitoring: true
+  });
+});
+
+onBeforeUnmount(() => agent?.destroy());
 ```
 
-This updates both `package.json` and `package-lock.json`.
+## How Widget Resolution Works
+
+At startup or first send, Pulse Agent calls:
+
+```text
+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.
+
+Do not confuse these values:
+
+| Name | Format | Purpose | User action |
+| --- | --- | --- | --- |
+| `appKey` | `app_...` | Public application key from Pulse Dashboard | Put in config/env. |
+| `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. |
+
+## Error Monitoring
+
+Error monitoring is opt-in. Installing the package does not capture anything until `errorMonitoring: true` is passed to `createPulseAgent`.
+
+When enabled, Pulse Agent can capture:
+
+- Unhandled JavaScript errors from `window.onerror`.
+- Unhandled promise rejections from `window.onunhandledrejection`.
+- Failed `fetch` responses, including HTTP statuses from failed API calls.
+- Network errors thrown by `fetch`.
+- Manual error reports through `agent.captureException(...)`.
+
+Manual capture example:
+
+```ts
+try {
+  await saveOrder();
+} catch (error) {
+  agent.captureException(error, {
+    source: 'checkout.saveOrder',
+    errorType: 'checkout-error',
+    endpoint: '/api/orders',
+    pageUrl: window.location.href
+  });
+  throw error;
+}
+```
+
+Report count example:
+
+```ts
+const reportsLastSevenDays = agent.getErrorReportCount(7);
+```
+
+### What Error Monitoring Does Not Do
+
+Pulse Agent does not:
+
+- Catch errors before the widget is initialized.
+- Catch server-side errors unless those errors are exposed to the browser as failed requests.
+- Replace backend logging, APM, or infrastructure monitoring.
+- Read private app state, passwords, tokens, or request bodies intentionally.
+- Automatically fix errors.
+- Capture errors if `errorMonitoring` is missing or `false`.
+
+## Public Backend Endpoints
+
+The widget expects these Pulse endpoints:
+
+```text
+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>
+GET  /api/pulse/public/webchat/{widgetToken}/stream?conversationId=<id>
+POST /api/pulse/public/webchat/{widgetToken}/errors
+```
+
+Admin setup endpoints are separate and should remain authenticated.
+
+## Benefits
+
+- One package for webchat and optional browser error monitoring.
+- 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/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
+
+- Browser-only. Initialize after mount/hydration in SSR frameworks.
+- Requires the website origin to be allowed by Pulse CORS configuration.
+- Requires an active Pulse Webchat integration for the organization/application.
+- Requires `fetch` and `EventSource` support for full behavior.
+- SSE can be affected by proxies, corporate networks, browser extensions, and load balancer timeouts.
+- Error monitoring starts only after initialization and only when enabled.
+- `fetch` monitoring covers `window.fetch`; it does not automatically wrap Axios internals unless Axios uses `fetch` in that environment.
+- `widgetToken` is an advanced bypass and should not be used unless Pulse explicitly provides it.
+
+## Production Checklist
+
+Before publishing a site with Pulse Agent:
+
+1. Confirm Pulse Webchat is enabled in the Pulse Dashboard.
+2. Confirm you have the correct `slug`.
+3. Confirm you have the correct `appKey` beginning with `app_`.
+4. Confirm `apiBaseUrl` is `https://pulse.service.primexperts.co.za`.
+5. Confirm production origin is allowed by Pulse CORS configuration.
+6. Confirm `runtime-config.js` or app config is generated from deployment env values.
+7. Confirm `errorMonitoring` is `true` if you expect browser error reporting.
+8. Open the site and check browser network calls for `resolve`, `message`, `stream`, and `errors` when applicable.
+9. Send a test chat message.
+10. Trigger a test error in a non-production or controlled environment and confirm it appears in Pulse.
+
+## Handle API
+
+`createPulseAgent(options)` returns:
+
+| Method | Description |
+| --- | --- |
+| `open()` | Opens the chat panel. |
+| `close()` | Closes the chat panel. |
+| `destroy()` | Removes DOM, listeners, and fetch wrapping installed by this instance. |
+| `resetConversation()` | Starts a fresh local conversation. |
+| `update(partialOptions)` | Updates runtime options such as title, WhatsApp URL, or widget token. |
+| `captureException(error, context)` | Manually reports an error when monitoring is enabled. |
+| `getErrorReportCount(days)` | Returns locally remembered successful error report count for the last N days. |
+
+## Troubleshooting
+
+### The widget does not appear
+
+Check that initialization runs in the browser, the `slug` is present, and the mount selector exists.
+
+### `Failed to resolve widget keys (401/403)`
+
+The public resolve endpoint is protected or the key is not accepted. Confirm the Pulse public webchat routes are accessible and the `appKey` is correct.
+
+### `Failed to resolve widget keys (404)`
+
+The slug is wrong, Webchat is not enabled, or the selected organization/application has no active widget.
+
+### CORS error in the browser console
+
+The website origin is missing from Pulse CORS configuration. Add the exact origin, including protocol and port.
+
+### Chat sends but replies do not stream
+
+Check that `EventSource` is available and that proxies/load balancers allow long-lived SSE connections.
+
+### Errors are not captured
+
+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`.

package/docs/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes for Pulse Agent documentation and integration behavior are listed here.
+
+## 2026-03-02
+
+### Added
+- `docs/INTEGRATION-CHANNELS.md` with channel-based integration documentation for:
+  - Webchat (public widget + realtime SSE flow)
+  - Email (IMAPS ingestion + scheduler behavior)
+  - WhatsApp (planned/reserved status)
+
+### Changed
+- `README.md` documentation section now links to the integration channels guide.
+
+## 2026-02-28
+
+### Added
+- `docs/IMPLEMENTATION-GUIDE.md` with end-to-end implementation instructions.
+- `docs/FAQ.md` for common integration and deployment questions.
+- `docs/TROUBLESHOOTING.md` with error-based diagnostics and fixes.
+
+### Changed
+- Standardized API base URL guidance to:
+  - `https://pulse.service.primexperts.co.za`
+- Removed manual organization key fallback flow from widget implementation.
+- Updated setup behavior to rely on slug-based resolve endpoint.
+- Updated README examples and notes to match current widget behavior.
+
+### Notes
+- Public webchat flow depends on backend exposing public endpoints and correct CORS allowlist.

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

@@ -0,0 +1,58 @@
+# Pulse Agent FAQ
+
+## What is Pulse Agent?
+
+Pulse Agent is an embeddable browser chat widget for websites. It connects to Pulse public webchat endpoints to resolve an organization and start conversations.
+
+## Which API base URL should I use?
+
+Use:
+
+`https://pulse.service.primexperts.co.za`
+
+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`
+
+## Do users need to log in to use the widget?
+
+For public website chat, no. Public webchat endpoints should allow anonymous access.
+
+## Which endpoints must be public?
+
+- `GET /api/pulse/public/webchat/resolve?slug=<slug>`
+- `POST /api/pulse/public/webchat/{widgetToken}/message`
+- `GET /api/pulse/public/webchat/{widgetToken}/stream?conversationId=<id>`
+
+## Why do I get CORS errors on localhost?
+
+Your frontend origin is not in backend CORS allowlist. Add:
+
+- `http://localhost:4200` (and other local ports you use)
+
+## Does this support Angular, React, and Vue?
+
+Yes. Any browser-based frontend can use it.
+
+## Does this work in SSR?
+
+Only on the client side. Initialize after mount/hydration.
+
+## What does 401/403 from resolve mean?
+
+The resolve endpoint is protected. For anonymous website chat, make it public.
+
+## What does 404 from resolve mean?
+
+No active webchat widget exists for that slug, or slug is wrong.
+
+## What should I secure if endpoints are public?
+
+- Rate limiting
+- Payload size limits
+- Input validation
+- Anti-spam controls
+

package/docs/IMPLEMENTATION-GUIDE.md

@@ -0,0 +1,324 @@
+# 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. 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
+
+Pulse Agent is a browser widget for public websites. It provides:
+
+- Floating Pulse Webchat launcher.
+- Visitor profile capture before chat, when enabled.
+- Public chat message ingestion.
+- Conversation history loading.
+- Realtime replies through Server-Sent Events.
+- Optional transcript/follow-up email action.
+- 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. 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 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
+
+```bash
+npm install @primexperts.co/pulse-agent@latest
+```
+
+For script-tag usage:
+
+```html
+<script src="https://unpkg.com/@primexperts.co/pulse-agent@latest/dist/browser/pulse-agent.global.js"></script>
+```
+
+## 4. Basic Configuration
+
+```ts
+import { createPulseAgent } from '@primexperts.co/pulse-agent';
+
+createPulseAgent({
+  slug: 'vayakids',
+  appKey: 'app_your_public_application_key',
+  apiBaseUrl: 'https://pulse.service.primexperts.co.za',
+  title: 'VayaKids',
+  requireProfile: true,
+  autoOpen: false
+});
+```
+
+## 5. Error Monitoring Configuration
+
+Error monitoring is off by default. Enable it explicitly:
+
+```ts
+createPulseAgent({
+  slug: 'vayakids',
+  appKey: 'app_your_public_application_key',
+  apiBaseUrl: 'https://pulse.service.primexperts.co.za',
+  errorMonitoring: true,
+  captureUnhandledErrors: true,
+  captureUnhandledRejections: true,
+  captureFetchErrors: true,
+  environment: 'production',
+  release: 'web-1.0.0'
+});
+```
+
+When enabled, Pulse Agent reports:
+
+- Unhandled browser errors.
+- Unhandled promise rejections.
+- Failed `fetch` HTTP responses.
+- Network errors thrown by `fetch`.
+- Manual errors reported through `captureException`.
+
+Manual capture:
+
+```ts
+const agent = createPulseAgent({
+  slug: 'vayakids',
+  appKey: 'app_your_public_application_key',
+  apiBaseUrl: 'https://pulse.service.primexperts.co.za',
+  errorMonitoring: true
+});
+
+try {
+  await loadImportantData();
+} catch (error) {
+  agent.captureException(error, {
+    source: 'home.loadImportantData',
+    errorType: 'data-load-error',
+    endpoint: '/api/important-data',
+    pageUrl: window.location.href
+  });
+  throw error;
+}
+```
+
+## 6. Environment Variable Names
+
+Use these names in Heroku, Docker, CI, or your hosting platform:
+
+```env
+PULSE_AGENT_SLUG=vayakids
+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_ENVIRONMENT=production
+PULSE_AGENT_RELEASE=web-1.0.0
+
+PULSE_AGENT_ERROR_MONITORING=true
+PULSE_AGENT_CAPTURE_UNHANDLED_ERRORS=true
+PULSE_AGENT_CAPTURE_UNHANDLED_REJECTIONS=true
+PULSE_AGENT_CAPTURE_FETCH_ERRORS=true
+```
+
+Optional:
+
+```env
+PULSE_AGENT_FOLLOW_UP_EMAIL_TO=support@example.com
+PULSE_AGENT_DASHBOARD_URL=https://pulse.primexperts.co.za
+PULSE_AGENT_DASHBOARD_SETUP_PATH=/integrations
+PULSE_AGENT_AUTO_OPEN=false
+PULSE_AGENT_REQUIRE_PROFILE=true
+PULSE_AGENT_WHATSAPP_URL=https://api.whatsapp.com/send?phone=27123456789
+PULSE_AGENT_WIDGET_TOKEN=
+```
+
+Leave `PULSE_AGENT_WIDGET_TOKEN` empty unless Pulse tells you to use 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.
+
+Add this to `index.html` before your app bundle:
+
+```html
+<script src="/runtime-config.js"></script>
+```
+
+Example `runtime-config.js` output:
+
+```js
+window.__APP_RUNTIME_CONFIG__ = {
+  pulseAgent: {
+    slug: 'vayakids',
+    appKey: 'app_your_public_application_key',
+    apiBaseUrl: 'https://pulse.service.primexperts.co.za',
+    title: 'VayaKids',
+    errorMonitoring: true,
+    captureUnhandledErrors: true,
+    captureUnhandledRejections: true,
+    captureFetchErrors: true,
+    environment: 'production',
+    release: 'web-1.0.0'
+  }
+};
+```
+
+Initialize from that config:
+
+```ts
+import { createPulseAgent, type PulseAgentOptions } from '@primexperts.co/pulse-agent';
+
+declare global {
+  interface Window {
+    __APP_RUNTIME_CONFIG__?: {
+      pulseAgent?: Partial<PulseAgentOptions>;
+    };
+  }
+}
+
+const pulseAgentConfig = window.__APP_RUNTIME_CONFIG__?.pulseAgent;
+
+if (pulseAgentConfig?.slug) {
+  createPulseAgent({
+    ...pulseAgentConfig,
+    slug: pulseAgentConfig.slug
+  });
+}
+```
+
+## 8. Heroku Setup
+
+Set config vars:
+
+```bash
+heroku config:set PULSE_AGENT_SLUG=vayakids
+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_ENVIRONMENT=production
+heroku config:set PULSE_AGENT_ERROR_MONITORING=true
+heroku config:set PULSE_AGENT_CAPTURE_UNHANDLED_ERRORS=true
+heroku config:set PULSE_AGENT_CAPTURE_UNHANDLED_REJECTIONS=true
+heroku config:set PULSE_AGENT_CAPTURE_FETCH_ERRORS=true
+```
+
+If your app uses a generated `public/runtime-config.js`, run the generator during build or startup. If your app serves `/runtime-config.js` from Node/Express, read `process.env` and emit the config response at request time.
+
+## 9. Framework Notes
+
+### Angular
+
+Initialize in `main.ts` or a browser-only root component. If Angular Universal is used, guard with `typeof window !== 'undefined'`.
+
+### React
+
+Initialize inside a top-level `useEffect`. Return `agent.destroy()` from cleanup if the component can unmount.
+
+### Vue
+
+Initialize in `onMounted` and destroy in `onBeforeUnmount`.
+
+### Next.js and Nuxt
+
+Use a client-only component/plugin. Do not initialize during server rendering.
+
+### Static HTML
+
+Use the browser global bundle and call `window.PulseAgent.createPulseAgent(...)` after the script loads.
+
+## 10. Public Endpoints Used By The Widget
+
+Pulse Agent calls these public endpoints:
+
+```text
+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>
+GET  /api/pulse/public/webchat/{widgetToken}/stream?conversationId=<id>
+POST /api/pulse/public/webchat/{widgetToken}/errors
+```
+
+These endpoints are public by design for website visitors. Admin setup endpoints must remain authenticated.
+
+## 11. Benefits
+
+- One small browser package for chat and optional error reporting.
+- No visitor login required.
+- No need for customers to manage internal widget tokens.
+- Supports runtime config for Heroku and similar platforms.
+- Works with npm, module bundlers, or a CDN script tag.
+- Supports multiple frontend frameworks.
+- Uses standard browser APIs: `fetch`, `EventSource`, and DOM events.
+
+## 12. Limitations
+
+- Browser-only; no server-side rendering execution.
+- Requires CORS configuration for every website origin.
+- Requires active Pulse Webchat configuration.
+- Requires network access to Pulse API.
+- SSE streaming may be interrupted by proxies or timeout policies.
+- Error monitoring starts only after initialization.
+- Error monitoring does not replace backend logs or APM.
+- `captureFetchErrors` wraps `window.fetch`; non-fetch HTTP clients may need manual reporting.
+- `widgetToken` is advanced and should usually remain unset.
+
+## 13. Verification Checklist
+
+1. Open the site and confirm the Pulse launcher appears.
+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.
+6. If transcript email is enabled, confirm the transcript endpoint succeeds.
+7. If error monitoring is enabled, trigger a controlled test error and confirm `/errors` succeeds.
+8. Confirm Pulse Dashboard shows the expected conversation/error entries.
+
+## 14. Troubleshooting
+
+### Nothing happens after install
+
+Installation alone does not run the widget. Your app must import the package and call `createPulseAgent(...)`.
+
+### The app key starts with `app_`; where does it go?
+
+Use it as `appKey`, or as `PULSE_AGENT_APP_KEY` in environment config.
+
+### Where do I get `widgetToken`?
+
+Usually nowhere. The widget resolves it automatically from `slug` and `appKey`. Leave `widgetToken` unset unless Pulse gives you one directly.
+
+### Errors are not being reported
+
+Check that `errorMonitoring` is true, the widget resolves successfully, and the error occurs after initialization.
+
+### CORS blocks requests
+
+Add the exact frontend origin to Pulse CORS/backend allowlist.
+
+### Resolve returns 404
+
+Check organization slug, app key, and whether Webchat is enabled for the selected organization/application.
+
+### Resolve returns 401 or 403
+
+Check whether the public resolve route is accessible and whether the app key is valid.

package/docs/INTEGRATION-CHANNELS.md

@@ -0,0 +1,143 @@
+# Pulse Integration Channels Guide
+
+This guide documents how to integrate Pulse by channel type and which technologies are used by each integration.
+
+## 1. Channel Support Matrix
+
+| Channel | Current Status | Main Purpose | Supporting Technologies |
+|---|---|---|---|
+| Webchat | Supported | Public website visitor chat | `@primexperts.co/pulse-agent` widget, REST APIs, SSE realtime stream, browser `fetch`/`EventSource`, CORS |
+| Email | Supported | Ingest inbound mailbox emails into Pulse conversations | IMAPS polling (`jakarta.mail`), scheduled worker (`@Scheduled every 5m`), REST admin config APIs |
+| WhatsApp | Planned (type exists, no active API flow) | Future messaging channel | Data model/enum placeholders only |
+
+## 2. Common Integration Flow
+
+1. Configure integration in authenticated admin APIs under `/api/pulse/integrations/*`.
+2. Enable integration and verify status is `ACTIVE`.
+3. Send/receive messages through channel-specific endpoints/workers.
+4. Monitor `lastSyncAt` and operational logs for health.
+
+## 3. Webchat Integration
+
+### 3.1 What You Need
+
+- Frontend: browser app or website.
+- Package: `@primexperts.co/pulse-agent`.
+- API base URL (example): `https://pulse.service.primexperts.co.za`.
+- Organization slug with active webchat integration.
+
+### 3.2 Admin Endpoints (Authenticated)
+
+- `GET /api/pulse/integrations`
+- `POST /api/pulse/integrations/webchat`
+- `POST /api/pulse/integrations/{type}/disable`
+- `GET /api/pulse/integrations/webchat/snippet`
+
+### 3.3 Public Endpoints (Unauthenticated)
+
+- `GET /api/pulse/public/webchat/resolve?slug=<slug>`
+- `POST /api/pulse/public/webchat/{widgetToken}/message`
+- `GET /api/pulse/public/webchat/{widgetToken}/messages?conversationId=<uuid>`
+- `POST /api/pulse/public/webchat/{widgetToken}/transcript-email?conversationId=<uuid>`
+- `GET /api/pulse/public/webchat/{widgetToken}/stream?conversationId=<uuid>` (SSE)
+
+### 3.4 Example Widget Bootstrap
+
+```ts
+import { createPulseAgent } from '@primexperts.co/pulse-agent';
+
+createPulseAgent({
+  slug: 'primexperts',
+  apiBaseUrl: 'https://pulse.service.primexperts.co.za',
+  requireProfile: true
+});
+```
+
+### 3.5 Supporting Technologies
+
+- Browser runtime (framework-agnostic).
+- Realtime via Server-Sent Events (`EventSource`).
+- JSON over HTTPS (`fetch`).
+- Backend rate limiting per widget token on public ingest.
+- CORS allowlist on Pulse API.
+
+## 4. Email Integration
+
+### 4.1 What You Need
+
+- Admin access to configure mailbox credentials.
+- Reachable IMAPS inbox server.
+- Dedicated mailbox credentials recommended.
+
+### 4.2 Admin Endpoints (Authenticated)
+
+- `GET /api/pulse/integrations`
+- `POST /api/pulse/integrations/email`
+- `PATCH /api/pulse/integrations/email`
+- `POST /api/pulse/integrations/email/test`
+- `POST /api/pulse/integrations/{type}/disable`
+
+### 4.3 Email Config Payload
+
+```json
+{
+  "inboxHost": "imap.example.com",
+  "inboxPort": 993,
+  "inboxUsername": "support@example.com",
+  "inboxPassword": "********",
+  "inboxFolder": "INBOX",
+  "smtpHost": "smtp.example.com",
+  "smtpUsername": "support@example.com",
+  "smtpPassword": "********"
+}
+```
+
+### 4.4 Runtime Behavior
+
+- A scheduler polls active email integrations every `5m` (after initial startup delay).
+- Ingestion uses IMAPS (`mail.store.protocol=imaps`, SSL enabled).
+- Unread messages are converted into Pulse conversations/messages.
+- Deduplication is handled using `Message-ID` and a computed fingerprint.
+- Conversation source is stored as `EMAIL`.
+
+### 4.5 Supporting Technologies
+
+- `jakarta.mail` for mailbox access.
+- Quarkus scheduler (`@Scheduled`) for polling.
+- Domain events + realtime publish for newly ingested messages.
+- Notification service hooks for integration status and transcript emails.
+
+## 5. WhatsApp Integration
+
+### 5.1 Current State
+
+- `WHATSAPP` exists in enums and DB constraints.
+- No dedicated configure/ingest API resource is currently exposed.
+- No worker or provider adapter is currently implemented.
+
+### 5.2 Integration Planning Notes
+
+- Treat as reserved channel type until APIs and provider contracts are added.
+- Do not mark it as production-ready in client-facing onboarding docs yet.
+
+## 6. Security and Operations Checklist
+
+- Keep admin integration APIs protected with bearer auth.
+- Keep only public webchat endpoints unauthenticated.
+- Enforce CORS allowlist for website origins.
+- Rotate mailbox credentials and monitor failed IMAPS logins.
+- Confirm SSE support in reverse proxy/load balancer configuration.
+
+## 7. Quick Start by Team
+
+### Frontend Team
+
+1. Integrate `@primexperts.co/pulse-agent`.
+2. Configure slug and API base URL.
+3. Validate resolve -> message -> stream flow in browser network logs.
+
+### Backend/Platform Team
+
+1. Enable `WEBCHAT` and/or configure `EMAIL` integration.
+2. Confirm integration records are `ACTIVE`.
+3. Monitor `lastSyncAt`, ingestion logs, and rate-limit behavior.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,86 @@
+# Pulse Agent Troubleshooting
+
+## 1) CORS: `No 'Access-Control-Allow-Origin' header`
+
+### Symptoms
+- Browser blocks requests to Pulse API.
+- Console shows CORS policy errors.
+
+### Fix
+- Ensure backend CORS includes your frontend origin.
+- Example allowed origins:
+  - `https://pulse.primexperts.co.za`
+  - `http://localhost:4200`
+
+## 2) Wrong API host called in network tab
+
+### Symptoms
+- Requests go to old/incorrect host (e.g., `api.pulsecrm.com`).
+
+### Fix
+- Set widget config explicitly:
+  - `apiBaseUrl: 'https://pulse.service.primexperts.co.za'`
+- Clear stale local config in app storage if applicable.
+
+## 3) Resolve endpoint returns 401 or 403
+
+### Symptoms
+- `GET /api/pulse/public/webchat/resolve?slug=...` is unauthorized.
+
+### Fix
+- Mark public webchat endpoints as anonymous/permitAll in backend security.
+
+## 4) Resolve endpoint returns 404
+
+### Symptoms
+- `Failed to resolve widget keys (404)` message.
+
+### Fix
+- Verify slug is correct.
+- Ensure webchat integration is enabled for that organization.
+
+## 5) Stream not receiving agent messages
+
+### Symptoms
+- Message POST works, no realtime replies appear.
+
+### Fix
+- Verify SSE endpoint is reachable:
+  - `GET /api/pulse/public/webchat/{widgetToken}/stream?conversationId=<id>`
+- Check proxies/load balancers for SSE support and timeouts.
+
+## 6) Keycloak timeout logs
+
+### Symptoms
+- Logs like `Keycloak init timed out`.
+
+### Fix
+- Confirm Keycloak URL/realm/client config.
+- Verify redirect URIs and web origins in Keycloak client.
+- Treat separately from webchat CORS unless proven linked.
+
+## 7) Slug validation quick check
+
+If slug is generated using:
+
+```sql
+regexp_replace(
+  regexp_replace(lower(trim(name)), '[^a-z0-9]+', '-', 'g'),
+  '(^-+|-+$)', '', 'g'
+)
+```
+
+Then:
+- `PrimeXperts` -> `primexperts`
+
+Resolve URL:
+
+`https://pulse.service.primexperts.co.za/api/pulse/public/webchat/resolve?slug=primexperts`
+
+## 8) Quick verification checklist
+
+- Widget config uses correct `apiBaseUrl`
+- Backend CORS includes current frontend origin
+- Public webchat endpoints are accessible without auth
+- Organization slug is correct
+- Webchat integration is active

package/package.json

@@ -1,39 +1,40 @@
-{
-  "name": "@primexperts.co/pulse-agent",
-  "version": "5.1.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",
-    "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"
+  }
+}