@primexperts.co/pulse-agent 5.4.0 → 5.6.0

package/README.md

@@ -158,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:
@@ -307,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`.

package/docs/IMPLEMENTATION-GUIDE.md

@@ -79,6 +79,19 @@ createPulseAgent({
 });
 ```
 
+## 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:
@@ -160,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.

package/package.json

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