@customerhero/js 0.0.2 → 1.0.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.
Files changed (5) hide show
  1. package/dist/index.cjs +983 -47
  2. package/dist/index.d.cts +87 -4
  3. package/dist/index.d.ts +87 -4
  4. package/dist/index.js +973 -46
  5. package/package.json +1 -1
package/dist/index.d.cts CHANGED
@@ -1,5 +1,14 @@
1
- type TranslationKey = "online" | "typing" | "unable_to_load" | "powered_by" | "new_conversation" | "open_chat" | "close_chat" | "send_message" | "helpful" | "not_helpful" | "menu";
1
+ type TranslationKey = "online" | "typing" | "unable_to_load" | "powered_by" | "new_conversation" | "open_chat" | "close_chat" | "send_message" | "helpful" | "not_helpful" | "menu" | "action_approve" | "action_cancel" | "action_what_will_happen" | "action_already_resolved" | "action_failed" | "status_sending" | "status_sent" | "status_failed" | "screenshot_capture" | "attachment_remove";
2
+ type Translations = Record<TranslationKey, string>;
3
+
4
+ declare const SUPPORTED_LOCALES: readonly ["en", "es", "pt-BR", "pt-PT", "fr", "de", "it", "nl", "pl", "tr", "ar", "ja", "ko", "zh-CN", "zh-TW"];
5
+ type SupportedLocale = (typeof SUPPORTED_LOCALES)[number];
6
+ declare function isRtlLocale(locale: string): boolean;
7
+ declare function resolveLocale(locale: string | undefined): SupportedLocale;
8
+ declare function detectLocale(explicit?: string): SupportedLocale;
9
+ type StringOverrides = Partial<Record<TranslationKey, Partial<Record<string, string>>>>;
2
10
  type TranslateFn = (key: TranslationKey) => string;
11
+ declare function createTranslator(locale: SupportedLocale, overrides?: StringOverrides): TranslateFn;
3
12
 
4
13
  interface CustomerHeroChatConfig {
5
14
  /** The chatbot ID to connect to */
@@ -27,6 +36,7 @@ interface CustomerHeroChatConfig {
27
36
  /** Predefined quick-reply options shown before the user sends a message */
28
37
  suggestedMessages?: string[];
29
38
  }
39
+
30
40
  interface ResolvedConfig {
31
41
  chatbotId: string;
32
42
  apiBase: string;
@@ -39,12 +49,53 @@ interface ResolvedConfig {
39
49
  title: string;
40
50
  avatarUrl?: string;
41
51
  suggestedMessages: string[];
52
+ /** Per-chatbot overrides for any translation key, optionally per-locale. */
53
+ stringOverrides?: StringOverrides;
42
54
  }
55
+ interface MessageSource {
56
+ index: number;
57
+ title: string;
58
+ url?: string;
59
+ dataSourceId: string;
60
+ heading?: string;
61
+ }
62
+ type QuickRepliesBlock = {
63
+ type: "quick_replies";
64
+ options: string[];
65
+ };
66
+ type ActionConfirmationBlock = {
67
+ type: "action_confirmation";
68
+ pendingToolCallId: string;
69
+ actionName: string;
70
+ title: string;
71
+ summary: string;
72
+ approveHref: string;
73
+ cancelHref: string;
74
+ };
75
+ type MessageBlock = QuickRepliesBlock | ActionConfirmationBlock;
76
+ type MessageStatus = "sending" | "sent" | "failed";
43
77
  interface ChatMessage {
44
78
  /** Message ID from the API (only present for bot messages) */
45
79
  id?: string;
46
80
  role: "user" | "bot";
47
81
  content: string;
82
+ /** Source citations referenced inline with `[n]` markers. Bot only. */
83
+ sources?: MessageSource[];
84
+ /** Structured blocks (quick-reply chips, etc.) rendered with the bubble. */
85
+ blocks?: MessageBlock[];
86
+ /**
87
+ * Follow-up questions the customer might plausibly ask next. Rendered as
88
+ * tappable chips under the most recent bot message only.
89
+ */
90
+ suggestions?: string[];
91
+ /** True while this message is still receiving streaming tokens. */
92
+ streaming?: boolean;
93
+ /**
94
+ * Local-only delivery status. User messages only — `sending` until the
95
+ * SSE `metadata` event lands, then `sent`. `failed` if the POST never
96
+ * reached the server. Bot messages use `streaming` instead.
97
+ */
98
+ status?: MessageStatus;
48
99
  }
49
100
  type MessageRating = "positive" | "negative";
50
101
  interface IdentifyPayload {
@@ -82,6 +133,10 @@ interface ChatState {
82
133
  configError: string | null;
83
134
  error: string | null;
84
135
  identity: IdentityData | null;
136
+ /** Active locale (one of `SUPPORTED_LOCALES`). */
137
+ locale: SupportedLocale;
138
+ /** True when the active locale is right-to-left. */
139
+ isRtl: boolean;
85
140
  }
86
141
 
87
142
  type Listener = (state: ChatState) => void;
@@ -91,15 +146,34 @@ declare class CustomerHeroChat {
91
146
  private storage;
92
147
  private userConfig;
93
148
  private identityData;
94
- readonly t: TranslateFn;
149
+ t: TranslateFn;
95
150
  constructor(config: CustomerHeroChatConfig);
151
+ setLocale(tag: string): void;
152
+ private rebuildTranslator;
96
153
  subscribe(listener: Listener): () => void;
97
154
  getState(): ChatState;
98
155
  private setState;
156
+ private patchLastMessage;
99
157
  private notifyListeners;
100
158
  fetchConfig(): Promise<void>;
101
159
  private loadHistory;
102
- sendMessage(message: string): Promise<void>;
160
+ sendMessage(message: string, options?: {
161
+ attachmentTokens?: string[];
162
+ }): Promise<void>;
163
+ uploadAttachment(blob: Blob, options?: {
164
+ filename?: string;
165
+ }): Promise<{
166
+ attachmentToken: string;
167
+ previewUrl: string;
168
+ expiresAt: string;
169
+ }>;
170
+ approveAction(pendingId: string): Promise<void>;
171
+ cancelAction(pendingId: string): Promise<void>;
172
+ private sendDecision;
173
+ private findActionConfirmationMessageIndex;
174
+ private patchMessageAt;
175
+ private appendToMessageAt;
176
+ private appendBlockToMessageAt;
103
177
  rateMessage(messageId: string, rating: MessageRating): Promise<void>;
104
178
  toggle(): void;
105
179
  open(): void;
@@ -119,4 +193,13 @@ declare const DEFAULTS: {
119
193
  title: string;
120
194
  };
121
195
 
122
- export { type ChatMessage, type ChatState, CustomerHeroChat, type CustomerHeroChatConfig, DEFAULTS, type IdentifyPayload, type IdentityData, type MessageRating, type ResolvedConfig, type TranslateFn, type TranslationKey };
196
+ declare class ScreenshotCancelled extends Error {
197
+ constructor(message?: string);
198
+ }
199
+ declare class ScreenshotUnavailable extends Error {
200
+ constructor(message?: string);
201
+ }
202
+ declare function canCaptureScreenshot(): boolean;
203
+ declare function captureScreenshot(): Promise<Blob>;
204
+
205
+ export { type ActionConfirmationBlock, type ChatMessage, type ChatState, CustomerHeroChat, type CustomerHeroChatConfig, DEFAULTS, type IdentifyPayload, type IdentityData, type MessageBlock, type MessageRating, type MessageSource, type MessageStatus, type QuickRepliesBlock, type ResolvedConfig, SUPPORTED_LOCALES, ScreenshotCancelled, ScreenshotUnavailable, type StringOverrides, type SupportedLocale, type TranslateFn, type TranslationKey, type Translations, canCaptureScreenshot, captureScreenshot, createTranslator, detectLocale, isRtlLocale, resolveLocale };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,14 @@
1
- type TranslationKey = "online" | "typing" | "unable_to_load" | "powered_by" | "new_conversation" | "open_chat" | "close_chat" | "send_message" | "helpful" | "not_helpful" | "menu";
1
+ type TranslationKey = "online" | "typing" | "unable_to_load" | "powered_by" | "new_conversation" | "open_chat" | "close_chat" | "send_message" | "helpful" | "not_helpful" | "menu" | "action_approve" | "action_cancel" | "action_what_will_happen" | "action_already_resolved" | "action_failed" | "status_sending" | "status_sent" | "status_failed" | "screenshot_capture" | "attachment_remove";
2
+ type Translations = Record<TranslationKey, string>;
3
+
4
+ declare const SUPPORTED_LOCALES: readonly ["en", "es", "pt-BR", "pt-PT", "fr", "de", "it", "nl", "pl", "tr", "ar", "ja", "ko", "zh-CN", "zh-TW"];
5
+ type SupportedLocale = (typeof SUPPORTED_LOCALES)[number];
6
+ declare function isRtlLocale(locale: string): boolean;
7
+ declare function resolveLocale(locale: string | undefined): SupportedLocale;
8
+ declare function detectLocale(explicit?: string): SupportedLocale;
9
+ type StringOverrides = Partial<Record<TranslationKey, Partial<Record<string, string>>>>;
2
10
  type TranslateFn = (key: TranslationKey) => string;
11
+ declare function createTranslator(locale: SupportedLocale, overrides?: StringOverrides): TranslateFn;
3
12
 
4
13
  interface CustomerHeroChatConfig {
5
14
  /** The chatbot ID to connect to */
@@ -27,6 +36,7 @@ interface CustomerHeroChatConfig {
27
36
  /** Predefined quick-reply options shown before the user sends a message */
28
37
  suggestedMessages?: string[];
29
38
  }
39
+
30
40
  interface ResolvedConfig {
31
41
  chatbotId: string;
32
42
  apiBase: string;
@@ -39,12 +49,53 @@ interface ResolvedConfig {
39
49
  title: string;
40
50
  avatarUrl?: string;
41
51
  suggestedMessages: string[];
52
+ /** Per-chatbot overrides for any translation key, optionally per-locale. */
53
+ stringOverrides?: StringOverrides;
42
54
  }
55
+ interface MessageSource {
56
+ index: number;
57
+ title: string;
58
+ url?: string;
59
+ dataSourceId: string;
60
+ heading?: string;
61
+ }
62
+ type QuickRepliesBlock = {
63
+ type: "quick_replies";
64
+ options: string[];
65
+ };
66
+ type ActionConfirmationBlock = {
67
+ type: "action_confirmation";
68
+ pendingToolCallId: string;
69
+ actionName: string;
70
+ title: string;
71
+ summary: string;
72
+ approveHref: string;
73
+ cancelHref: string;
74
+ };
75
+ type MessageBlock = QuickRepliesBlock | ActionConfirmationBlock;
76
+ type MessageStatus = "sending" | "sent" | "failed";
43
77
  interface ChatMessage {
44
78
  /** Message ID from the API (only present for bot messages) */
45
79
  id?: string;
46
80
  role: "user" | "bot";
47
81
  content: string;
82
+ /** Source citations referenced inline with `[n]` markers. Bot only. */
83
+ sources?: MessageSource[];
84
+ /** Structured blocks (quick-reply chips, etc.) rendered with the bubble. */
85
+ blocks?: MessageBlock[];
86
+ /**
87
+ * Follow-up questions the customer might plausibly ask next. Rendered as
88
+ * tappable chips under the most recent bot message only.
89
+ */
90
+ suggestions?: string[];
91
+ /** True while this message is still receiving streaming tokens. */
92
+ streaming?: boolean;
93
+ /**
94
+ * Local-only delivery status. User messages only — `sending` until the
95
+ * SSE `metadata` event lands, then `sent`. `failed` if the POST never
96
+ * reached the server. Bot messages use `streaming` instead.
97
+ */
98
+ status?: MessageStatus;
48
99
  }
49
100
  type MessageRating = "positive" | "negative";
50
101
  interface IdentifyPayload {
@@ -82,6 +133,10 @@ interface ChatState {
82
133
  configError: string | null;
83
134
  error: string | null;
84
135
  identity: IdentityData | null;
136
+ /** Active locale (one of `SUPPORTED_LOCALES`). */
137
+ locale: SupportedLocale;
138
+ /** True when the active locale is right-to-left. */
139
+ isRtl: boolean;
85
140
  }
86
141
 
87
142
  type Listener = (state: ChatState) => void;
@@ -91,15 +146,34 @@ declare class CustomerHeroChat {
91
146
  private storage;
92
147
  private userConfig;
93
148
  private identityData;
94
- readonly t: TranslateFn;
149
+ t: TranslateFn;
95
150
  constructor(config: CustomerHeroChatConfig);
151
+ setLocale(tag: string): void;
152
+ private rebuildTranslator;
96
153
  subscribe(listener: Listener): () => void;
97
154
  getState(): ChatState;
98
155
  private setState;
156
+ private patchLastMessage;
99
157
  private notifyListeners;
100
158
  fetchConfig(): Promise<void>;
101
159
  private loadHistory;
102
- sendMessage(message: string): Promise<void>;
160
+ sendMessage(message: string, options?: {
161
+ attachmentTokens?: string[];
162
+ }): Promise<void>;
163
+ uploadAttachment(blob: Blob, options?: {
164
+ filename?: string;
165
+ }): Promise<{
166
+ attachmentToken: string;
167
+ previewUrl: string;
168
+ expiresAt: string;
169
+ }>;
170
+ approveAction(pendingId: string): Promise<void>;
171
+ cancelAction(pendingId: string): Promise<void>;
172
+ private sendDecision;
173
+ private findActionConfirmationMessageIndex;
174
+ private patchMessageAt;
175
+ private appendToMessageAt;
176
+ private appendBlockToMessageAt;
103
177
  rateMessage(messageId: string, rating: MessageRating): Promise<void>;
104
178
  toggle(): void;
105
179
  open(): void;
@@ -119,4 +193,13 @@ declare const DEFAULTS: {
119
193
  title: string;
120
194
  };
121
195
 
122
- export { type ChatMessage, type ChatState, CustomerHeroChat, type CustomerHeroChatConfig, DEFAULTS, type IdentifyPayload, type IdentityData, type MessageRating, type ResolvedConfig, type TranslateFn, type TranslationKey };
196
+ declare class ScreenshotCancelled extends Error {
197
+ constructor(message?: string);
198
+ }
199
+ declare class ScreenshotUnavailable extends Error {
200
+ constructor(message?: string);
201
+ }
202
+ declare function canCaptureScreenshot(): boolean;
203
+ declare function captureScreenshot(): Promise<Blob>;
204
+
205
+ export { type ActionConfirmationBlock, type ChatMessage, type ChatState, CustomerHeroChat, type CustomerHeroChatConfig, DEFAULTS, type IdentifyPayload, type IdentityData, type MessageBlock, type MessageRating, type MessageSource, type MessageStatus, type QuickRepliesBlock, type ResolvedConfig, SUPPORTED_LOCALES, ScreenshotCancelled, ScreenshotUnavailable, type StringOverrides, type SupportedLocale, type TranslateFn, type TranslationKey, type Translations, canCaptureScreenshot, captureScreenshot, createTranslator, detectLocale, isRtlLocale, resolveLocale };