@channlize/core 0.2.1 → 0.4.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/CHANGELOG.md +22 -0
- package/README.md +22 -14
- package/dist/index.d.mts +123 -19
- package/dist/index.d.ts +123 -19
- package/dist/index.js +130 -31
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +121 -30
- package/dist/index.mjs.map +1 -1
- package/package.json +8 -6
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,27 @@
|
|
|
1
1
|
# @channlize/core
|
|
2
2
|
|
|
3
|
+
## 0.4.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 5663cd2: Make `@channlize/core` the single source for what the packages share.
|
|
8
|
+
|
|
9
|
+
- core exports `DEFAULT_BASE_URL`, `DEFAULT_TIMEOUT`, `EVENT_SEVERITIES`, `EVENT_KEY_PATTERN`, `isValidEventKey`, `keyKind` (widget vs. server key), `readChannlizeEnv` (the `CHANNLIZE_*` variables) and `parseApiError` (the API's error shape). `createNotifier`, the client and `@channlize/mcp` use them instead of their own copies.
|
|
10
|
+
- `ChannlizeError` gains `requestId` and `details` (the API's error body, e.g. `limit`, `used` and `resetAt` on a plan-limit 429). When a legacy route puts its human-readable text in `error`, it becomes the message instead of `HTTP <status>`.
|
|
11
|
+
- The chat types document where the API differs from them (ISO string timestamps, session summaries without `messages`).
|
|
12
|
+
- `@channlize/react` and `@channlize/mcp` re-export the error classes as values, so `instanceof` works without importing core.
|
|
13
|
+
- mcp tool errors no longer end with a doubled period when a core error message ends with one.
|
|
14
|
+
|
|
15
|
+
- Release every `@channlize/*` package under one shared version. From 0.4.0 on, core, react, mcp and skills always publish together at the same version, so matching versions work together.
|
|
16
|
+
|
|
17
|
+
## 0.2.2
|
|
18
|
+
|
|
19
|
+
Not published on its own; these changes ship in 0.4.0.
|
|
20
|
+
|
|
21
|
+
### Patch Changes
|
|
22
|
+
|
|
23
|
+
- 097ad44: Log tracking no longer throws when the API refuses an event with a 429: `trackEvent` and `trackServerEvent` resolve with `{ success: false, id: '', dropped: 'plan_limit' | 'rate_limit' }` and log one console warning, so reaching the plan's log tracking limit (`PLAN_LIMIT_REACHED`) or the rate limit never breaks the calling app. `RateLimitError.code` is now `PLAN_LIMIT_REACHED` for plan-limit refusals (for example from `notify()`), and `TrackEventResult` is exported.
|
|
24
|
+
|
|
3
25
|
## 0.2.1
|
|
4
26
|
|
|
5
27
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -25,7 +25,7 @@ await notify('user.subscribed', { username: user.name, plan: 'Pro' });
|
|
|
25
25
|
import { ChannlizeClient } from '@channlize/core';
|
|
26
26
|
|
|
27
27
|
const client = new ChannlizeClient({
|
|
28
|
-
apiKey: '
|
|
28
|
+
apiKey: 'wk_…', // public widget key
|
|
29
29
|
projectId: 'your-project-id',
|
|
30
30
|
baseUrl: 'https://api.channlize.com', // optional
|
|
31
31
|
timeout: 10000, // optional, default 10s
|
|
@@ -47,18 +47,15 @@ const response = await client.submitContactForm({
|
|
|
47
47
|
},
|
|
48
48
|
});
|
|
49
49
|
|
|
50
|
-
console.log('
|
|
51
|
-
console.log('Slack thread:', response.slackThreadUrl);
|
|
50
|
+
console.log('Conversation:', response.conversationId);
|
|
52
51
|
```
|
|
53
52
|
|
|
54
53
|
### Chat Sessions
|
|
55
54
|
|
|
56
55
|
```typescript
|
|
57
56
|
// Create a new chat session
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
pageUrl: window.location.href,
|
|
61
|
-
});
|
|
57
|
+
// Metadata is optional; pageUrl and userAgent are added in the browser.
|
|
58
|
+
const sessionResponse = await client.createChatSession({ plan: 'pro' });
|
|
62
59
|
|
|
63
60
|
const session = sessionResponse.session;
|
|
64
61
|
|
|
@@ -149,6 +146,10 @@ await client.trackEvent('page.viewed', { properties: { path: '/pricing' } });
|
|
|
149
146
|
await client.trackServerEvent('webhook.received', { severity: 'warning' });
|
|
150
147
|
```
|
|
151
148
|
|
|
149
|
+
Log tracking never breaks your app over limits: when the API answers `429` (the rate limit, or your plan's log tracking limit for the billing period, `PLAN_LIMIT_REACHED`), both calls resolve with `{ success: false, id: '', dropped: 'plan_limit' | 'rate_limit' }` instead of throwing, and the client logs one console warning. Other errors (bad input, network) still throw.
|
|
150
|
+
|
|
151
|
+
`notify()` is different: a `429` there throws a `RateLimitError` whose `code` is `PLAN_LIMIT_REACHED` when the plan's Events limit is reached, so your server can see that the Slack message was not sent.
|
|
152
|
+
|
|
152
153
|
### Error Handling
|
|
153
154
|
|
|
154
155
|
```typescript
|
|
@@ -201,8 +202,8 @@ interface ChannlizeConfig {
|
|
|
201
202
|
- `getChatMessages(sessionId: string, limit?: number, offset?: number): Promise<ChatMessage[]>`
|
|
202
203
|
- `closeChatSession(sessionId: string): Promise<ChatSession>`
|
|
203
204
|
- `notify(event: string, data?: Record<string, unknown>, options?: NotifyOptions): Promise<NotifyResponse>` — Events (server)
|
|
204
|
-
- `trackEvent(name: string, options?: TrackEventOptions)
|
|
205
|
-
- `trackServerEvent(name: string, options?)
|
|
205
|
+
- `trackEvent(name: string, options?: TrackEventOptions): Promise<TrackEventResult>` — log tracking (browser); a 429 resolves with `dropped`
|
|
206
|
+
- `trackServerEvent(name: string, options?): Promise<TrackEventResult>` — log tracking (server); a 429 resolves with `dropped`
|
|
206
207
|
|
|
207
208
|
### createNotifier
|
|
208
209
|
|
|
@@ -210,7 +211,7 @@ interface ChannlizeConfig {
|
|
|
210
211
|
|
|
211
212
|
### Types
|
|
212
213
|
|
|
213
|
-
All TypeScript types are exported from the package:
|
|
214
|
+
All TypeScript types are exported from the package. The error classes (`ChannlizeError`, `ValidationError`, `AuthenticationError`, `RateLimitError`) are values, so import them without `type` for `instanceof` checks (see Error Handling):
|
|
214
215
|
|
|
215
216
|
```typescript
|
|
216
217
|
import type {
|
|
@@ -222,13 +223,20 @@ import type {
|
|
|
222
223
|
CreateContactResponse,
|
|
223
224
|
CreateChatSessionResponse,
|
|
224
225
|
SendMessageResponse,
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
AuthenticationError,
|
|
228
|
-
RateLimitError,
|
|
226
|
+
NotifyResponse,
|
|
227
|
+
TrackEventResult,
|
|
229
228
|
} from '@channlize/core';
|
|
230
229
|
```
|
|
231
230
|
|
|
231
|
+
## Documentation
|
|
232
|
+
|
|
233
|
+
- Guide: https://channlize.com/docs/core
|
|
234
|
+
- All docs: https://channlize.com/docs (quick start, API keys, troubleshooting)
|
|
235
|
+
|
|
236
|
+
## Changelog
|
|
237
|
+
|
|
238
|
+
[CHANGELOG.md](./CHANGELOG.md) lists every release of `@channlize/core`. Product updates: https://channlize.com/docs/changelog
|
|
239
|
+
|
|
232
240
|
## License
|
|
233
241
|
|
|
234
242
|
MIT
|
package/dist/index.d.mts
CHANGED
|
@@ -1,8 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Helpers shared by `@channlize/core`, `@channlize/react` and
|
|
3
|
+
* `@channlize/mcp`: defaults, key detection, environment variables, event
|
|
4
|
+
* keys and the API's error shape. Core is the single source for these.
|
|
5
|
+
*/
|
|
6
|
+
/** Default API base URL. */
|
|
7
|
+
declare const DEFAULT_BASE_URL = "https://api.channlize.com";
|
|
8
|
+
/** Default request timeout, in milliseconds. */
|
|
9
|
+
declare const DEFAULT_TIMEOUT = 10000;
|
|
10
|
+
/** Log tracking severities, lowest first. */
|
|
11
|
+
declare const EVENT_SEVERITIES: readonly ["info", "warning", "error"];
|
|
12
|
+
/**
|
|
13
|
+
* Valid Events key (same rule as the API): lowercase letters, digits,
|
|
14
|
+
* dots, underscores and dashes, e.g. `user.subscribed`. At most 100
|
|
15
|
+
* characters.
|
|
16
|
+
*/
|
|
17
|
+
declare const EVENT_KEY_PATTERN: RegExp;
|
|
18
|
+
/** Whether `event` is a valid Events key for `notify`. */
|
|
19
|
+
declare function isValidEventKey(event: unknown): event is string;
|
|
20
|
+
type KeyKind = 'widget' | 'server';
|
|
21
|
+
/**
|
|
22
|
+
* `wk_…` is the public widget key (browser: contact form, chat, browser
|
|
23
|
+
* log tracking); anything else is a server API key (`ch_live_…`).
|
|
24
|
+
*/
|
|
25
|
+
declare function keyKind(key: string): KeyKind;
|
|
26
|
+
/** The `CHANNLIZE_*` environment variables, trimmed (empty → undefined). */
|
|
27
|
+
interface ChannlizeEnv {
|
|
28
|
+
/** `CHANNLIZE_SERVER_API_KEY` */
|
|
29
|
+
serverApiKey?: string;
|
|
30
|
+
/** `CHANNLIZE_WIDGET_KEY` */
|
|
31
|
+
widgetKey?: string;
|
|
32
|
+
/** `CHANNLIZE_API_KEY` (either kind of key) */
|
|
33
|
+
apiKey?: string;
|
|
34
|
+
/** `CHANNLIZE_PROJECT_ID` */
|
|
35
|
+
projectId?: string;
|
|
36
|
+
/** `CHANNLIZE_BASE_URL` */
|
|
37
|
+
baseUrl?: string;
|
|
38
|
+
/** `CHANNLIZE_TIMEOUT` (milliseconds, unparsed) */
|
|
39
|
+
timeout?: string;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* Reads the `CHANNLIZE_*` environment variables. Safe in browsers and edge
|
|
43
|
+
* runtimes without `process` (everything is undefined there).
|
|
44
|
+
*/
|
|
45
|
+
declare function readChannlizeEnv(env?: Record<string, string | undefined> | undefined): ChannlizeEnv;
|
|
46
|
+
/** A failed API response, parsed from its JSON body. */
|
|
47
|
+
interface ApiErrorInfo {
|
|
48
|
+
status: number;
|
|
49
|
+
/** Human-readable text (field messages joined with `, `). */
|
|
50
|
+
message: string;
|
|
51
|
+
/** Machine-readable code: the body's `code`, else its `error` (e.g. `NOT_FOUND`). */
|
|
52
|
+
code?: string;
|
|
53
|
+
/** `requestId` from the body, to quote to support. */
|
|
54
|
+
requestId?: string;
|
|
55
|
+
/** The parsed body (e.g. `limit`, `used`, `resetAt` on a plan-limit 429). */
|
|
56
|
+
body: Record<string, unknown>;
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Parses the API's error shape (`api/lib/api/error.ts`):
|
|
60
|
+
* `{ statusCode, error: "NOT_FOUND", message: string | string[], requestId? }`.
|
|
61
|
+
* A few legacy routes put the human text in `error`.
|
|
62
|
+
*/
|
|
63
|
+
declare function parseApiError(status: number, body: unknown, statusText?: string): ApiErrorInfo;
|
|
64
|
+
|
|
1
65
|
/**
|
|
2
66
|
* Core types for Channlize SDK
|
|
3
67
|
*/
|
|
68
|
+
|
|
4
69
|
/** Severity for log tracking (`trackEvent` / `trackServerEvent`); Slack alerts use project settings. */
|
|
5
|
-
type EventSeverity =
|
|
70
|
+
type EventSeverity = (typeof EVENT_SEVERITIES)[number];
|
|
6
71
|
/** Options for log tracking (`trackEvent` / `trackServerEvent`). */
|
|
7
72
|
interface TrackEventOptions {
|
|
8
73
|
properties?: Record<string, unknown>;
|
|
@@ -105,11 +170,15 @@ interface ChatMessage {
|
|
|
105
170
|
id: string;
|
|
106
171
|
/** Message content */
|
|
107
172
|
content: string;
|
|
108
|
-
/**
|
|
173
|
+
/**
|
|
174
|
+
* Message timestamp. The API sends an ISO 8601 string, which
|
|
175
|
+
* `ChannlizeClient` passes through as is; `@channlize/react` converts it
|
|
176
|
+
* to a `Date`. Wrap it in `new Date(...)` before using `Date` methods.
|
|
177
|
+
*/
|
|
109
178
|
timestamp: Date;
|
|
110
179
|
/** Message author (user or agent) */
|
|
111
180
|
author: 'user' | 'agent';
|
|
112
|
-
/** Author metadata */
|
|
181
|
+
/** Author metadata (`name` / `email` can be `null` in message history) */
|
|
113
182
|
authorData?: {
|
|
114
183
|
name?: string;
|
|
115
184
|
email?: string;
|
|
@@ -133,15 +202,23 @@ interface FileAttachment {
|
|
|
133
202
|
interface ChatSession {
|
|
134
203
|
/** Session ID */
|
|
135
204
|
id: string;
|
|
136
|
-
/**
|
|
205
|
+
/**
|
|
206
|
+
* Session status. `createChatSession` answers `active`; `getChatSession`
|
|
207
|
+
* and `closeChatSession` answer the conversation's status (`open`,
|
|
208
|
+
* `pending`, `resolved` or `closed`).
|
|
209
|
+
*/
|
|
137
210
|
status: 'active' | 'closed' | 'waiting';
|
|
138
|
-
/**
|
|
211
|
+
/**
|
|
212
|
+
* Messages in the session. Only `createChatSession` returns it (empty);
|
|
213
|
+
* `getChatSession`, `closeChatSession` and `sendMessage` return a session
|
|
214
|
+
* summary without it. Load history with `getChatMessages`.
|
|
215
|
+
*/
|
|
139
216
|
messages: ChatMessage[];
|
|
140
217
|
/** Session metadata */
|
|
141
218
|
metadata?: Record<string, unknown>;
|
|
142
|
-
/** Created timestamp */
|
|
219
|
+
/** Created timestamp (an ISO 8601 string on the wire; not sent by `closeChatSession`) */
|
|
143
220
|
createdAt: Date;
|
|
144
|
-
/** Updated timestamp */
|
|
221
|
+
/** Updated timestamp (an ISO 8601 string on the wire) */
|
|
145
222
|
updatedAt: Date;
|
|
146
223
|
}
|
|
147
224
|
interface ApiResponse<T = unknown> {
|
|
@@ -178,7 +255,7 @@ interface CreateChatSessionResponse {
|
|
|
178
255
|
interface SendMessageResponse {
|
|
179
256
|
/** The sent message */
|
|
180
257
|
message: ChatMessage;
|
|
181
|
-
/**
|
|
258
|
+
/** The session (the API sends only `id` and `status`) */
|
|
182
259
|
session: ChatSession;
|
|
183
260
|
}
|
|
184
261
|
/**
|
|
@@ -187,6 +264,13 @@ interface SendMessageResponse {
|
|
|
187
264
|
declare class ChannlizeError extends Error {
|
|
188
265
|
statusCode?: number | undefined;
|
|
189
266
|
code?: string | undefined;
|
|
267
|
+
/** The API's `requestId` for a failed response, to quote to support. */
|
|
268
|
+
requestId?: string;
|
|
269
|
+
/**
|
|
270
|
+
* The API's JSON error body, e.g. `limit`, `used`, `resetAt` and
|
|
271
|
+
* `upgradeUrl` on a plan-limit 429. Undefined for network errors.
|
|
272
|
+
*/
|
|
273
|
+
details?: Record<string, unknown>;
|
|
190
274
|
constructor(message: string, statusCode?: number | undefined, code?: string | undefined);
|
|
191
275
|
}
|
|
192
276
|
declare class ValidationError extends ChannlizeError {
|
|
@@ -196,8 +280,25 @@ declare class ValidationError extends ChannlizeError {
|
|
|
196
280
|
declare class AuthenticationError extends ChannlizeError {
|
|
197
281
|
constructor(message?: string);
|
|
198
282
|
}
|
|
283
|
+
/**
|
|
284
|
+
* A 429. `code` is `PLAN_LIMIT_REACHED` when the organization is past its
|
|
285
|
+
* plan's limit for the billing period (the API's 110 % hard cap), else
|
|
286
|
+
* `RATE_LIMIT_ERROR`.
|
|
287
|
+
*/
|
|
199
288
|
declare class RateLimitError extends ChannlizeError {
|
|
200
|
-
constructor(message?: string);
|
|
289
|
+
constructor(message?: string, code?: string);
|
|
290
|
+
}
|
|
291
|
+
/**
|
|
292
|
+
* What `trackEvent` / `trackServerEvent` resolve with. When the API refuses
|
|
293
|
+
* the event with a 429 (rate limit or plan limit), the call resolves with
|
|
294
|
+
* `success: false` and `dropped` instead of throwing: log tracking never
|
|
295
|
+
* breaks the app that calls it.
|
|
296
|
+
*/
|
|
297
|
+
interface TrackEventResult {
|
|
298
|
+
success: boolean;
|
|
299
|
+
id: string;
|
|
300
|
+
/** Set when the event was refused and not stored. */
|
|
301
|
+
dropped?: 'plan_limit' | 'rate_limit';
|
|
201
302
|
}
|
|
202
303
|
|
|
203
304
|
/**
|
|
@@ -242,10 +343,8 @@ declare class ChannlizeClient<TEvents extends object = ChannlizeEvents> {
|
|
|
242
343
|
* Log tracking: record a log line from the browser (widget key →
|
|
243
344
|
* `POST /public/events`). Shown under Log tracking in the dashboard.
|
|
244
345
|
*/
|
|
245
|
-
trackEvent(name: string, options?: TrackEventOptions): Promise<
|
|
246
|
-
|
|
247
|
-
id: string;
|
|
248
|
-
}>;
|
|
346
|
+
trackEvent(name: string, options?: TrackEventOptions): Promise<TrackEventResult>;
|
|
347
|
+
private sendBrowserEvent;
|
|
249
348
|
/**
|
|
250
349
|
* Log tracking from a trusted server, using the organization API key
|
|
251
350
|
* (`POST /v1/events`). Shown under Log tracking in the dashboard.
|
|
@@ -253,10 +352,15 @@ declare class ChannlizeClient<TEvents extends object = ChannlizeEvents> {
|
|
|
253
352
|
trackServerEvent(name: string, options?: {
|
|
254
353
|
properties?: Record<string, unknown>;
|
|
255
354
|
severity?: EventSeverity;
|
|
256
|
-
}): Promise<
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
355
|
+
}): Promise<TrackEventResult>;
|
|
356
|
+
/**
|
|
357
|
+
* Log tracking must never break the caller: a 429 (rate limit, or the
|
|
358
|
+
* plan's limit for the billing period) resolves with `success: false`
|
|
359
|
+
* and `dropped` instead of throwing, with one console warning per client.
|
|
360
|
+
*/
|
|
361
|
+
private nonFatalTracking;
|
|
362
|
+
private warnedDropped;
|
|
363
|
+
private sendServerEvent;
|
|
260
364
|
/**
|
|
261
365
|
* Events: post a Slack message from your server when something happens
|
|
262
366
|
* (`POST /v1/notify`). The event key picks the channel and message
|
|
@@ -284,5 +388,5 @@ type Notifier<TEvents extends object = ChannlizeEvents> = <K extends NotifyEvent
|
|
|
284
388
|
*/
|
|
285
389
|
declare function createNotifier<TEvents extends object = ChannlizeEvents>(config?: NotifierConfig): Notifier<TEvents>;
|
|
286
390
|
|
|
287
|
-
export { AuthenticationError, ChannlizeClient, ChannlizeError, RateLimitError, ValidationError, createNotifier, ChannlizeClient as default };
|
|
288
|
-
export type { ApiResponse, ChannlizeConfig, ChannlizeEvents, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, EventSeverity, FileAttachment, Notifier, NotifierConfig, NotifyEventData, NotifyEventName, NotifyOptions, NotifyResponse, SendMessageResponse, TrackEventOptions };
|
|
391
|
+
export { AuthenticationError, ChannlizeClient, ChannlizeError, DEFAULT_BASE_URL, DEFAULT_TIMEOUT, EVENT_KEY_PATTERN, EVENT_SEVERITIES, RateLimitError, ValidationError, createNotifier, ChannlizeClient as default, isValidEventKey, keyKind, parseApiError, readChannlizeEnv };
|
|
392
|
+
export type { ApiErrorInfo, ApiResponse, ChannlizeConfig, ChannlizeEnv, ChannlizeEvents, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, EventSeverity, FileAttachment, KeyKind, Notifier, NotifierConfig, NotifyEventData, NotifyEventName, NotifyOptions, NotifyResponse, SendMessageResponse, TrackEventOptions, TrackEventResult };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,8 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Helpers shared by `@channlize/core`, `@channlize/react` and
|
|
3
|
+
* `@channlize/mcp`: defaults, key detection, environment variables, event
|
|
4
|
+
* keys and the API's error shape. Core is the single source for these.
|
|
5
|
+
*/
|
|
6
|
+
/** Default API base URL. */
|
|
7
|
+
declare const DEFAULT_BASE_URL = "https://api.channlize.com";
|
|
8
|
+
/** Default request timeout, in milliseconds. */
|
|
9
|
+
declare const DEFAULT_TIMEOUT = 10000;
|
|
10
|
+
/** Log tracking severities, lowest first. */
|
|
11
|
+
declare const EVENT_SEVERITIES: readonly ["info", "warning", "error"];
|
|
12
|
+
/**
|
|
13
|
+
* Valid Events key (same rule as the API): lowercase letters, digits,
|
|
14
|
+
* dots, underscores and dashes, e.g. `user.subscribed`. At most 100
|
|
15
|
+
* characters.
|
|
16
|
+
*/
|
|
17
|
+
declare const EVENT_KEY_PATTERN: RegExp;
|
|
18
|
+
/** Whether `event` is a valid Events key for `notify`. */
|
|
19
|
+
declare function isValidEventKey(event: unknown): event is string;
|
|
20
|
+
type KeyKind = 'widget' | 'server';
|
|
21
|
+
/**
|
|
22
|
+
* `wk_…` is the public widget key (browser: contact form, chat, browser
|
|
23
|
+
* log tracking); anything else is a server API key (`ch_live_…`).
|
|
24
|
+
*/
|
|
25
|
+
declare function keyKind(key: string): KeyKind;
|
|
26
|
+
/** The `CHANNLIZE_*` environment variables, trimmed (empty → undefined). */
|
|
27
|
+
interface ChannlizeEnv {
|
|
28
|
+
/** `CHANNLIZE_SERVER_API_KEY` */
|
|
29
|
+
serverApiKey?: string;
|
|
30
|
+
/** `CHANNLIZE_WIDGET_KEY` */
|
|
31
|
+
widgetKey?: string;
|
|
32
|
+
/** `CHANNLIZE_API_KEY` (either kind of key) */
|
|
33
|
+
apiKey?: string;
|
|
34
|
+
/** `CHANNLIZE_PROJECT_ID` */
|
|
35
|
+
projectId?: string;
|
|
36
|
+
/** `CHANNLIZE_BASE_URL` */
|
|
37
|
+
baseUrl?: string;
|
|
38
|
+
/** `CHANNLIZE_TIMEOUT` (milliseconds, unparsed) */
|
|
39
|
+
timeout?: string;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* Reads the `CHANNLIZE_*` environment variables. Safe in browsers and edge
|
|
43
|
+
* runtimes without `process` (everything is undefined there).
|
|
44
|
+
*/
|
|
45
|
+
declare function readChannlizeEnv(env?: Record<string, string | undefined> | undefined): ChannlizeEnv;
|
|
46
|
+
/** A failed API response, parsed from its JSON body. */
|
|
47
|
+
interface ApiErrorInfo {
|
|
48
|
+
status: number;
|
|
49
|
+
/** Human-readable text (field messages joined with `, `). */
|
|
50
|
+
message: string;
|
|
51
|
+
/** Machine-readable code: the body's `code`, else its `error` (e.g. `NOT_FOUND`). */
|
|
52
|
+
code?: string;
|
|
53
|
+
/** `requestId` from the body, to quote to support. */
|
|
54
|
+
requestId?: string;
|
|
55
|
+
/** The parsed body (e.g. `limit`, `used`, `resetAt` on a plan-limit 429). */
|
|
56
|
+
body: Record<string, unknown>;
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Parses the API's error shape (`api/lib/api/error.ts`):
|
|
60
|
+
* `{ statusCode, error: "NOT_FOUND", message: string | string[], requestId? }`.
|
|
61
|
+
* A few legacy routes put the human text in `error`.
|
|
62
|
+
*/
|
|
63
|
+
declare function parseApiError(status: number, body: unknown, statusText?: string): ApiErrorInfo;
|
|
64
|
+
|
|
1
65
|
/**
|
|
2
66
|
* Core types for Channlize SDK
|
|
3
67
|
*/
|
|
68
|
+
|
|
4
69
|
/** Severity for log tracking (`trackEvent` / `trackServerEvent`); Slack alerts use project settings. */
|
|
5
|
-
type EventSeverity =
|
|
70
|
+
type EventSeverity = (typeof EVENT_SEVERITIES)[number];
|
|
6
71
|
/** Options for log tracking (`trackEvent` / `trackServerEvent`). */
|
|
7
72
|
interface TrackEventOptions {
|
|
8
73
|
properties?: Record<string, unknown>;
|
|
@@ -105,11 +170,15 @@ interface ChatMessage {
|
|
|
105
170
|
id: string;
|
|
106
171
|
/** Message content */
|
|
107
172
|
content: string;
|
|
108
|
-
/**
|
|
173
|
+
/**
|
|
174
|
+
* Message timestamp. The API sends an ISO 8601 string, which
|
|
175
|
+
* `ChannlizeClient` passes through as is; `@channlize/react` converts it
|
|
176
|
+
* to a `Date`. Wrap it in `new Date(...)` before using `Date` methods.
|
|
177
|
+
*/
|
|
109
178
|
timestamp: Date;
|
|
110
179
|
/** Message author (user or agent) */
|
|
111
180
|
author: 'user' | 'agent';
|
|
112
|
-
/** Author metadata */
|
|
181
|
+
/** Author metadata (`name` / `email` can be `null` in message history) */
|
|
113
182
|
authorData?: {
|
|
114
183
|
name?: string;
|
|
115
184
|
email?: string;
|
|
@@ -133,15 +202,23 @@ interface FileAttachment {
|
|
|
133
202
|
interface ChatSession {
|
|
134
203
|
/** Session ID */
|
|
135
204
|
id: string;
|
|
136
|
-
/**
|
|
205
|
+
/**
|
|
206
|
+
* Session status. `createChatSession` answers `active`; `getChatSession`
|
|
207
|
+
* and `closeChatSession` answer the conversation's status (`open`,
|
|
208
|
+
* `pending`, `resolved` or `closed`).
|
|
209
|
+
*/
|
|
137
210
|
status: 'active' | 'closed' | 'waiting';
|
|
138
|
-
/**
|
|
211
|
+
/**
|
|
212
|
+
* Messages in the session. Only `createChatSession` returns it (empty);
|
|
213
|
+
* `getChatSession`, `closeChatSession` and `sendMessage` return a session
|
|
214
|
+
* summary without it. Load history with `getChatMessages`.
|
|
215
|
+
*/
|
|
139
216
|
messages: ChatMessage[];
|
|
140
217
|
/** Session metadata */
|
|
141
218
|
metadata?: Record<string, unknown>;
|
|
142
|
-
/** Created timestamp */
|
|
219
|
+
/** Created timestamp (an ISO 8601 string on the wire; not sent by `closeChatSession`) */
|
|
143
220
|
createdAt: Date;
|
|
144
|
-
/** Updated timestamp */
|
|
221
|
+
/** Updated timestamp (an ISO 8601 string on the wire) */
|
|
145
222
|
updatedAt: Date;
|
|
146
223
|
}
|
|
147
224
|
interface ApiResponse<T = unknown> {
|
|
@@ -178,7 +255,7 @@ interface CreateChatSessionResponse {
|
|
|
178
255
|
interface SendMessageResponse {
|
|
179
256
|
/** The sent message */
|
|
180
257
|
message: ChatMessage;
|
|
181
|
-
/**
|
|
258
|
+
/** The session (the API sends only `id` and `status`) */
|
|
182
259
|
session: ChatSession;
|
|
183
260
|
}
|
|
184
261
|
/**
|
|
@@ -187,6 +264,13 @@ interface SendMessageResponse {
|
|
|
187
264
|
declare class ChannlizeError extends Error {
|
|
188
265
|
statusCode?: number | undefined;
|
|
189
266
|
code?: string | undefined;
|
|
267
|
+
/** The API's `requestId` for a failed response, to quote to support. */
|
|
268
|
+
requestId?: string;
|
|
269
|
+
/**
|
|
270
|
+
* The API's JSON error body, e.g. `limit`, `used`, `resetAt` and
|
|
271
|
+
* `upgradeUrl` on a plan-limit 429. Undefined for network errors.
|
|
272
|
+
*/
|
|
273
|
+
details?: Record<string, unknown>;
|
|
190
274
|
constructor(message: string, statusCode?: number | undefined, code?: string | undefined);
|
|
191
275
|
}
|
|
192
276
|
declare class ValidationError extends ChannlizeError {
|
|
@@ -196,8 +280,25 @@ declare class ValidationError extends ChannlizeError {
|
|
|
196
280
|
declare class AuthenticationError extends ChannlizeError {
|
|
197
281
|
constructor(message?: string);
|
|
198
282
|
}
|
|
283
|
+
/**
|
|
284
|
+
* A 429. `code` is `PLAN_LIMIT_REACHED` when the organization is past its
|
|
285
|
+
* plan's limit for the billing period (the API's 110 % hard cap), else
|
|
286
|
+
* `RATE_LIMIT_ERROR`.
|
|
287
|
+
*/
|
|
199
288
|
declare class RateLimitError extends ChannlizeError {
|
|
200
|
-
constructor(message?: string);
|
|
289
|
+
constructor(message?: string, code?: string);
|
|
290
|
+
}
|
|
291
|
+
/**
|
|
292
|
+
* What `trackEvent` / `trackServerEvent` resolve with. When the API refuses
|
|
293
|
+
* the event with a 429 (rate limit or plan limit), the call resolves with
|
|
294
|
+
* `success: false` and `dropped` instead of throwing: log tracking never
|
|
295
|
+
* breaks the app that calls it.
|
|
296
|
+
*/
|
|
297
|
+
interface TrackEventResult {
|
|
298
|
+
success: boolean;
|
|
299
|
+
id: string;
|
|
300
|
+
/** Set when the event was refused and not stored. */
|
|
301
|
+
dropped?: 'plan_limit' | 'rate_limit';
|
|
201
302
|
}
|
|
202
303
|
|
|
203
304
|
/**
|
|
@@ -242,10 +343,8 @@ declare class ChannlizeClient<TEvents extends object = ChannlizeEvents> {
|
|
|
242
343
|
* Log tracking: record a log line from the browser (widget key →
|
|
243
344
|
* `POST /public/events`). Shown under Log tracking in the dashboard.
|
|
244
345
|
*/
|
|
245
|
-
trackEvent(name: string, options?: TrackEventOptions): Promise<
|
|
246
|
-
|
|
247
|
-
id: string;
|
|
248
|
-
}>;
|
|
346
|
+
trackEvent(name: string, options?: TrackEventOptions): Promise<TrackEventResult>;
|
|
347
|
+
private sendBrowserEvent;
|
|
249
348
|
/**
|
|
250
349
|
* Log tracking from a trusted server, using the organization API key
|
|
251
350
|
* (`POST /v1/events`). Shown under Log tracking in the dashboard.
|
|
@@ -253,10 +352,15 @@ declare class ChannlizeClient<TEvents extends object = ChannlizeEvents> {
|
|
|
253
352
|
trackServerEvent(name: string, options?: {
|
|
254
353
|
properties?: Record<string, unknown>;
|
|
255
354
|
severity?: EventSeverity;
|
|
256
|
-
}): Promise<
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
355
|
+
}): Promise<TrackEventResult>;
|
|
356
|
+
/**
|
|
357
|
+
* Log tracking must never break the caller: a 429 (rate limit, or the
|
|
358
|
+
* plan's limit for the billing period) resolves with `success: false`
|
|
359
|
+
* and `dropped` instead of throwing, with one console warning per client.
|
|
360
|
+
*/
|
|
361
|
+
private nonFatalTracking;
|
|
362
|
+
private warnedDropped;
|
|
363
|
+
private sendServerEvent;
|
|
260
364
|
/**
|
|
261
365
|
* Events: post a Slack message from your server when something happens
|
|
262
366
|
* (`POST /v1/notify`). The event key picks the channel and message
|
|
@@ -284,5 +388,5 @@ type Notifier<TEvents extends object = ChannlizeEvents> = <K extends NotifyEvent
|
|
|
284
388
|
*/
|
|
285
389
|
declare function createNotifier<TEvents extends object = ChannlizeEvents>(config?: NotifierConfig): Notifier<TEvents>;
|
|
286
390
|
|
|
287
|
-
export { AuthenticationError, ChannlizeClient, ChannlizeError, RateLimitError, ValidationError, createNotifier, ChannlizeClient as default };
|
|
288
|
-
export type { ApiResponse, ChannlizeConfig, ChannlizeEvents, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, EventSeverity, FileAttachment, Notifier, NotifierConfig, NotifyEventData, NotifyEventName, NotifyOptions, NotifyResponse, SendMessageResponse, TrackEventOptions };
|
|
391
|
+
export { AuthenticationError, ChannlizeClient, ChannlizeError, DEFAULT_BASE_URL, DEFAULT_TIMEOUT, EVENT_KEY_PATTERN, EVENT_SEVERITIES, RateLimitError, ValidationError, createNotifier, ChannlizeClient as default, isValidEventKey, keyKind, parseApiError, readChannlizeEnv };
|
|
392
|
+
export type { ApiErrorInfo, ApiResponse, ChannlizeConfig, ChannlizeEnv, ChannlizeEvents, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, EventSeverity, FileAttachment, KeyKind, Notifier, NotifierConfig, NotifyEventData, NotifyEventName, NotifyOptions, NotifyResponse, SendMessageResponse, TrackEventOptions, TrackEventResult };
|