@primexperts.co/pulse-agent 5.0.0 → 5.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +401 -53
- package/dist/browser/pulse-agent.global.js +25 -9
- package/dist/widget/pulse-agent.d.ts +2 -0
- package/dist/widget/pulse-agent.d.ts.map +1 -1
- package/dist/widget/pulse-agent.js +25 -9
- package/dist/widget/pulse-agent.js.map +1 -1
- package/docs/CHANGELOG.md +31 -0
- package/docs/FAQ.md +58 -0
- package/docs/IMPLEMENTATION-GUIDE.md +309 -0
- package/docs/INTEGRATION-CHANNELS.md +143 -0
- package/docs/TROUBLESHOOTING.md +86 -0
- package/package.json +37 -36
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
# Pulse Integration Channels Guide
|
|
2
|
+
|
|
3
|
+
This guide documents how to integrate Pulse by channel type and which technologies are used by each integration.
|
|
4
|
+
|
|
5
|
+
## 1. Channel Support Matrix
|
|
6
|
+
|
|
7
|
+
| Channel | Current Status | Main Purpose | Supporting Technologies |
|
|
8
|
+
|---|---|---|---|
|
|
9
|
+
| Webchat | Supported | Public website visitor chat | `@primexperts.co/pulse-agent` widget, REST APIs, SSE realtime stream, browser `fetch`/`EventSource`, CORS |
|
|
10
|
+
| Email | Supported | Ingest inbound mailbox emails into Pulse conversations | IMAPS polling (`jakarta.mail`), scheduled worker (`@Scheduled every 5m`), REST admin config APIs |
|
|
11
|
+
| WhatsApp | Planned (type exists, no active API flow) | Future messaging channel | Data model/enum placeholders only |
|
|
12
|
+
|
|
13
|
+
## 2. Common Integration Flow
|
|
14
|
+
|
|
15
|
+
1. Configure integration in authenticated admin APIs under `/api/pulse/integrations/*`.
|
|
16
|
+
2. Enable integration and verify status is `ACTIVE`.
|
|
17
|
+
3. Send/receive messages through channel-specific endpoints/workers.
|
|
18
|
+
4. Monitor `lastSyncAt` and operational logs for health.
|
|
19
|
+
|
|
20
|
+
## 3. Webchat Integration
|
|
21
|
+
|
|
22
|
+
### 3.1 What You Need
|
|
23
|
+
|
|
24
|
+
- Frontend: browser app or website.
|
|
25
|
+
- Package: `@primexperts.co/pulse-agent`.
|
|
26
|
+
- API base URL (example): `https://pulse.service.primexperts.co.za`.
|
|
27
|
+
- Organization slug with active webchat integration.
|
|
28
|
+
|
|
29
|
+
### 3.2 Admin Endpoints (Authenticated)
|
|
30
|
+
|
|
31
|
+
- `GET /api/pulse/integrations`
|
|
32
|
+
- `POST /api/pulse/integrations/webchat`
|
|
33
|
+
- `POST /api/pulse/integrations/{type}/disable`
|
|
34
|
+
- `GET /api/pulse/integrations/webchat/snippet`
|
|
35
|
+
|
|
36
|
+
### 3.3 Public Endpoints (Unauthenticated)
|
|
37
|
+
|
|
38
|
+
- `GET /api/pulse/public/webchat/resolve?slug=<slug>`
|
|
39
|
+
- `POST /api/pulse/public/webchat/{widgetToken}/message`
|
|
40
|
+
- `GET /api/pulse/public/webchat/{widgetToken}/messages?conversationId=<uuid>`
|
|
41
|
+
- `POST /api/pulse/public/webchat/{widgetToken}/transcript-email?conversationId=<uuid>`
|
|
42
|
+
- `GET /api/pulse/public/webchat/{widgetToken}/stream?conversationId=<uuid>` (SSE)
|
|
43
|
+
|
|
44
|
+
### 3.4 Example Widget Bootstrap
|
|
45
|
+
|
|
46
|
+
```ts
|
|
47
|
+
import { createPulseAgent } from '@primexperts.co/pulse-agent';
|
|
48
|
+
|
|
49
|
+
createPulseAgent({
|
|
50
|
+
slug: 'primexperts',
|
|
51
|
+
apiBaseUrl: 'https://pulse.service.primexperts.co.za',
|
|
52
|
+
requireProfile: true
|
|
53
|
+
});
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### 3.5 Supporting Technologies
|
|
57
|
+
|
|
58
|
+
- Browser runtime (framework-agnostic).
|
|
59
|
+
- Realtime via Server-Sent Events (`EventSource`).
|
|
60
|
+
- JSON over HTTPS (`fetch`).
|
|
61
|
+
- Backend rate limiting per widget token on public ingest.
|
|
62
|
+
- CORS allowlist on Pulse API.
|
|
63
|
+
|
|
64
|
+
## 4. Email Integration
|
|
65
|
+
|
|
66
|
+
### 4.1 What You Need
|
|
67
|
+
|
|
68
|
+
- Admin access to configure mailbox credentials.
|
|
69
|
+
- Reachable IMAPS inbox server.
|
|
70
|
+
- Dedicated mailbox credentials recommended.
|
|
71
|
+
|
|
72
|
+
### 4.2 Admin Endpoints (Authenticated)
|
|
73
|
+
|
|
74
|
+
- `GET /api/pulse/integrations`
|
|
75
|
+
- `POST /api/pulse/integrations/email`
|
|
76
|
+
- `PATCH /api/pulse/integrations/email`
|
|
77
|
+
- `POST /api/pulse/integrations/email/test`
|
|
78
|
+
- `POST /api/pulse/integrations/{type}/disable`
|
|
79
|
+
|
|
80
|
+
### 4.3 Email Config Payload
|
|
81
|
+
|
|
82
|
+
```json
|
|
83
|
+
{
|
|
84
|
+
"inboxHost": "imap.example.com",
|
|
85
|
+
"inboxPort": 993,
|
|
86
|
+
"inboxUsername": "support@example.com",
|
|
87
|
+
"inboxPassword": "********",
|
|
88
|
+
"inboxFolder": "INBOX",
|
|
89
|
+
"smtpHost": "smtp.example.com",
|
|
90
|
+
"smtpUsername": "support@example.com",
|
|
91
|
+
"smtpPassword": "********"
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### 4.4 Runtime Behavior
|
|
96
|
+
|
|
97
|
+
- A scheduler polls active email integrations every `5m` (after initial startup delay).
|
|
98
|
+
- Ingestion uses IMAPS (`mail.store.protocol=imaps`, SSL enabled).
|
|
99
|
+
- Unread messages are converted into Pulse conversations/messages.
|
|
100
|
+
- Deduplication is handled using `Message-ID` and a computed fingerprint.
|
|
101
|
+
- Conversation source is stored as `EMAIL`.
|
|
102
|
+
|
|
103
|
+
### 4.5 Supporting Technologies
|
|
104
|
+
|
|
105
|
+
- `jakarta.mail` for mailbox access.
|
|
106
|
+
- Quarkus scheduler (`@Scheduled`) for polling.
|
|
107
|
+
- Domain events + realtime publish for newly ingested messages.
|
|
108
|
+
- Notification service hooks for integration status and transcript emails.
|
|
109
|
+
|
|
110
|
+
## 5. WhatsApp Integration
|
|
111
|
+
|
|
112
|
+
### 5.1 Current State
|
|
113
|
+
|
|
114
|
+
- `WHATSAPP` exists in enums and DB constraints.
|
|
115
|
+
- No dedicated configure/ingest API resource is currently exposed.
|
|
116
|
+
- No worker or provider adapter is currently implemented.
|
|
117
|
+
|
|
118
|
+
### 5.2 Integration Planning Notes
|
|
119
|
+
|
|
120
|
+
- Treat as reserved channel type until APIs and provider contracts are added.
|
|
121
|
+
- Do not mark it as production-ready in client-facing onboarding docs yet.
|
|
122
|
+
|
|
123
|
+
## 6. Security and Operations Checklist
|
|
124
|
+
|
|
125
|
+
- Keep admin integration APIs protected with bearer auth.
|
|
126
|
+
- Keep only public webchat endpoints unauthenticated.
|
|
127
|
+
- Enforce CORS allowlist for website origins.
|
|
128
|
+
- Rotate mailbox credentials and monitor failed IMAPS logins.
|
|
129
|
+
- Confirm SSE support in reverse proxy/load balancer configuration.
|
|
130
|
+
|
|
131
|
+
## 7. Quick Start by Team
|
|
132
|
+
|
|
133
|
+
### Frontend Team
|
|
134
|
+
|
|
135
|
+
1. Integrate `@primexperts.co/pulse-agent`.
|
|
136
|
+
2. Configure slug and API base URL.
|
|
137
|
+
3. Validate resolve -> message -> stream flow in browser network logs.
|
|
138
|
+
|
|
139
|
+
### Backend/Platform Team
|
|
140
|
+
|
|
141
|
+
1. Enable `WEBCHAT` and/or configure `EMAIL` integration.
|
|
142
|
+
2. Confirm integration records are `ACTIVE`.
|
|
143
|
+
3. Monitor `lastSyncAt`, ingestion logs, and rate-limit behavior.
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# Pulse Agent Troubleshooting
|
|
2
|
+
|
|
3
|
+
## 1) CORS: `No 'Access-Control-Allow-Origin' header`
|
|
4
|
+
|
|
5
|
+
### Symptoms
|
|
6
|
+
- Browser blocks requests to Pulse API.
|
|
7
|
+
- Console shows CORS policy errors.
|
|
8
|
+
|
|
9
|
+
### Fix
|
|
10
|
+
- Ensure backend CORS includes your frontend origin.
|
|
11
|
+
- Example allowed origins:
|
|
12
|
+
- `https://pulse.primexperts.co.za`
|
|
13
|
+
- `http://localhost:4200`
|
|
14
|
+
|
|
15
|
+
## 2) Wrong API host called in network tab
|
|
16
|
+
|
|
17
|
+
### Symptoms
|
|
18
|
+
- Requests go to old/incorrect host (e.g., `api.pulsecrm.com`).
|
|
19
|
+
|
|
20
|
+
### Fix
|
|
21
|
+
- Set widget config explicitly:
|
|
22
|
+
- `apiBaseUrl: 'https://pulse.service.primexperts.co.za'`
|
|
23
|
+
- Clear stale local config in app storage if applicable.
|
|
24
|
+
|
|
25
|
+
## 3) Resolve endpoint returns 401 or 403
|
|
26
|
+
|
|
27
|
+
### Symptoms
|
|
28
|
+
- `GET /api/pulse/public/webchat/resolve?slug=...` is unauthorized.
|
|
29
|
+
|
|
30
|
+
### Fix
|
|
31
|
+
- Mark public webchat endpoints as anonymous/permitAll in backend security.
|
|
32
|
+
|
|
33
|
+
## 4) Resolve endpoint returns 404
|
|
34
|
+
|
|
35
|
+
### Symptoms
|
|
36
|
+
- `Failed to resolve widget keys (404)` message.
|
|
37
|
+
|
|
38
|
+
### Fix
|
|
39
|
+
- Verify slug is correct.
|
|
40
|
+
- Ensure webchat integration is enabled for that organization.
|
|
41
|
+
|
|
42
|
+
## 5) Stream not receiving agent messages
|
|
43
|
+
|
|
44
|
+
### Symptoms
|
|
45
|
+
- Message POST works, no realtime replies appear.
|
|
46
|
+
|
|
47
|
+
### Fix
|
|
48
|
+
- Verify SSE endpoint is reachable:
|
|
49
|
+
- `GET /api/pulse/public/webchat/{widgetToken}/stream?conversationId=<id>`
|
|
50
|
+
- Check proxies/load balancers for SSE support and timeouts.
|
|
51
|
+
|
|
52
|
+
## 6) Keycloak timeout logs
|
|
53
|
+
|
|
54
|
+
### Symptoms
|
|
55
|
+
- Logs like `Keycloak init timed out`.
|
|
56
|
+
|
|
57
|
+
### Fix
|
|
58
|
+
- Confirm Keycloak URL/realm/client config.
|
|
59
|
+
- Verify redirect URIs and web origins in Keycloak client.
|
|
60
|
+
- Treat separately from webchat CORS unless proven linked.
|
|
61
|
+
|
|
62
|
+
## 7) Slug validation quick check
|
|
63
|
+
|
|
64
|
+
If slug is generated using:
|
|
65
|
+
|
|
66
|
+
```sql
|
|
67
|
+
regexp_replace(
|
|
68
|
+
regexp_replace(lower(trim(name)), '[^a-z0-9]+', '-', 'g'),
|
|
69
|
+
'(^-+|-+$)', '', 'g'
|
|
70
|
+
)
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Then:
|
|
74
|
+
- `PrimeXperts` -> `primexperts`
|
|
75
|
+
|
|
76
|
+
Resolve URL:
|
|
77
|
+
|
|
78
|
+
`https://pulse.service.primexperts.co.za/api/pulse/public/webchat/resolve?slug=primexperts`
|
|
79
|
+
|
|
80
|
+
## 8) Quick verification checklist
|
|
81
|
+
|
|
82
|
+
- Widget config uses correct `apiBaseUrl`
|
|
83
|
+
- Backend CORS includes current frontend origin
|
|
84
|
+
- Public webchat endpoints are accessible without auth
|
|
85
|
+
- Organization slug is correct
|
|
86
|
+
- Webchat integration is active
|
package/package.json
CHANGED
|
@@ -1,39 +1,40 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
2
|
+
"name": "@primexperts.co/pulse-agent",
|
|
3
|
+
"version": "5.2.0",
|
|
4
|
+
"description": "Embeddable Pulse floating chat agent widget.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./dist/index.js",
|
|
7
|
+
"types": "./dist/index.d.ts",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": {
|
|
10
|
+
"types": "./dist/index.d.ts",
|
|
11
|
+
"default": "./dist/index.js"
|
|
12
|
+
}
|
|
13
|
+
},
|
|
14
|
+
"files": [
|
|
15
|
+
"dist",
|
|
16
|
+
"docs",
|
|
17
|
+
"README.md",
|
|
18
|
+
"LICENSE"
|
|
19
|
+
],
|
|
20
|
+
"scripts": {
|
|
21
|
+
"clean": "node -e \"if(require('fs').existsSync('dist')) require('fs').rmSync('dist',{recursive:true,force:true})\"",
|
|
22
|
+
"build:types": "tsc -p tsconfig.build.json",
|
|
23
|
+
"build:browser": "node scripts/build-browser-global.mjs",
|
|
24
|
+
"build": "npm run clean && npm run build:types && npm run build:browser",
|
|
25
|
+
"version:bump": "node scripts/bump-version.mjs",
|
|
26
|
+
"version:patch": "node scripts/bump-version.mjs patch",
|
|
27
|
+
"version:minor": "node scripts/bump-version.mjs minor",
|
|
28
|
+
"version:major": "node scripts/bump-version.mjs major",
|
|
29
|
+
"prepublishOnly": "npm run build"
|
|
30
|
+
},
|
|
31
|
+
"private": false,
|
|
32
|
+
"license": "MIT",
|
|
33
|
+
"author": "PrimExperts",
|
|
34
|
+
"dependencies": {
|
|
35
|
+
"tslib": "^2.8.1"
|
|
36
|
+
},
|
|
37
|
+
"devDependencies": {
|
|
38
|
+
"typescript": "~5.8.2"
|
|
12
39
|
}
|
|
13
|
-
},
|
|
14
|
-
"files": [
|
|
15
|
-
"dist",
|
|
16
|
-
"README.md",
|
|
17
|
-
"LICENSE"
|
|
18
|
-
],
|
|
19
|
-
"scripts": {
|
|
20
|
-
"clean": "node -e \"if(require('fs').existsSync('dist')) require('fs').rmSync('dist',{recursive:true,force:true})\"",
|
|
21
|
-
"build:types": "tsc -p tsconfig.build.json",
|
|
22
|
-
"build:browser": "node scripts/build-browser-global.mjs",
|
|
23
|
-
"build": "npm run clean && npm run build:types && npm run build:browser",
|
|
24
|
-
"version:bump": "node scripts/bump-version.mjs",
|
|
25
|
-
"version:patch": "node scripts/bump-version.mjs patch",
|
|
26
|
-
"version:minor": "node scripts/bump-version.mjs minor",
|
|
27
|
-
"version:major": "node scripts/bump-version.mjs major",
|
|
28
|
-
"prepublishOnly": "npm run build"
|
|
29
|
-
},
|
|
30
|
-
"private": false,
|
|
31
|
-
"license": "MIT",
|
|
32
|
-
"author": "PrimExperts",
|
|
33
|
-
"dependencies": {
|
|
34
|
-
"tslib": "^2.8.1"
|
|
35
|
-
},
|
|
36
|
-
"devDependencies": {
|
|
37
|
-
"typescript": "~5.8.2"
|
|
38
|
-
}
|
|
39
40
|
}
|