@wildix/xbees-connect 1.3.6 → 1.3.7

package/README.md

@@ -18,8 +18,8 @@ npm install @wildix/xbees-connect
 The integration can be launched in different modes via the `v` URL parameter:
 
 - `ui` - Standard UI mode (default)
-- `no-ui` - Data-only mode, no UI shown
-- `d` - Dialog/setup mode
+- `no-ui` / `daemon` - Data-only mode, no UI shown
+- `d` / `dialog` - Dialog/setup mode
 - `f` - Fullsize mode, integration takes full viewport dimensions
 
 You can check the current mode using:
@@ -27,10 +27,10 @@ You can check the current mode using:
 ```ts
 const client = Client.getInstance();
 
-client.showsUi();      // Returns true for UI modes (ui, d, f)
-client.isDataOnly();   // Returns true for no-ui mode
-client.isSetupDialog(); // Returns true for dialog mode (d)
-client.isFullsize();   // Returns true for fullsize mode (f)
+client.showsUi();       // Returns true for UI modes (ui, d, f)
+client.isDataOnly();    // Returns true for no-ui / daemon mode
+client.isSetupDialog(); // Returns true for dialog mode (d / dialog)
+client.isFullsize();    // Returns true for fullsize mode (f)
 ```
 
 ## Usage
@@ -41,136 +41,444 @@ import Client from "@wildix/xbees-connect";
 const xBeesClient = Client.getInstance();
 
 console.log(xBeesClient.version());
-
 ```
 
 ## API
 
+### Class helpers
+
+#### `Client.getInstance(): ConnectClient`
+
+Returns the singleton `Client` instance. Prefer this over `new Client()` to avoid duplicate message listeners.
+
+```ts
+const client = Client.getInstance();
+```
+
+#### `Client.initialize(renderer: () => Promise<void>): void`
+
+Calls `renderer` only when the integration runs in a UI mode (`showsUi() === true`). Use this as the entry point to conditionally boot your React/Vue tree.
+
+```ts
+Client.initialize(async () => {
+  ReactDOM.render(<App />, document.getElementById('root'));
+});
+```
+
+---
+
 ### Initialization
 
-#### `ready()`
+#### `ready(props?: SupportedPlatformVariant | ReadyExtendedProps): Promise<ResponseMessage>`
 
-Sends the signal to x-bees that iFrame is ready to be shown. iFrame should send it when the application starts and is ready.
+Sends the signal to x-bees that the iFrame is ready to be shown. Call this once when the application starts and is fully initialised. Accepts an optional platform variant string or an extended props object (e.g. `templateId`, `analyticTitle`).
 
-#### `isAuthorized: (payload: string) => Promise<ResponseFromChannel>`
+#### `isAuthorized(): Promise<ResponseMessage>`
 
 Sends the message to x-bees that the user is authorized and no more actions are required.
 
-#### `isNotAuthorized: (payload: string) => Promise<ResponseFromChannel>`
+#### `isNotAuthorized(): Promise<ResponseMessage>`
+
+Sends the message to x-bees that the user is not authorized and interaction is required.
+
+---
+
+### Identity and user data
+
+#### `version(): string`
+
+Returns the version string of the `xbees-connect` package.
+
+#### `getUserEmail(): string`
+
+Returns the email of the currently authenticated x-bees user, taken from URL parameters at construction time.
+
+#### `getUserPbxToken(): string`
+
+Returns the current PBX token. The token is updated automatically whenever the `PBX_TOKEN` event fires. The initial value is an empty string until the first token event is received.
+
+#### `getPbxDomain(): string`
+
+Returns the current PBX domain. Populated after user data is fetched from x-bees.
+
+#### `getUserExtension(): string | null`
+
+Returns the PBX extension of the current user, or `null` if not available.
+
+#### `getXBeesUser(): XBeesUser | null`
+
+Returns a cached `XBeesUser` object (`{ id, email, extension, domain, name }`) or `null` if the data has not been fetched yet. Triggers a background fetch on first call.
+
+> **Deprecated behaviour:** this method does not wait for the fetch to complete. If you need the user data before rendering, use `getXBeesUserAsync()` instead.
+
+#### `getXBeesUserAsync(): Promise<XBeesUser | null>`
+
+Asynchronous version of `getXBeesUser`. Waits for the user data to be fetched from x-bees before returning. Prefer this over the synchronous variant when the user object is required immediately.
+
+```ts
+const user = await client.getXBeesUserAsync();
+if (user) {
+  console.log(user.name, user.email);
+}
+```
+
+#### `getReferrer(): string`
+
+Returns the URL of the x-bees app that opened this integration, taken from URL parameters at construction time.
+
+#### `getBackToAppUrl(): string`
+
+Returns the deep-link URL that navigates the user back to this integration inside the x-bees app. The format differs between native and web platforms.
+
+#### `getStartPage(): StartPage | null`
+
+Returns the `StartPage` enum value parsed from the URL, or `null` if not present.
+
+#### `getProduct(): Product | null`
+
+Returns the `Product` enum value indicating from which x-bees product the integration was opened (e.g. contacts, conversations), or `null` if not specified.
+
+---
+
+### Environment and platform
+
+#### `isPlatformNative(): boolean`
+
+Returns `true` when x-bees is running inside a React Native WebView.
+
+#### `isPlatformWeb(): boolean`
+
+Returns `true` when x-bees is running in a web browser (iFrame).
+
+#### `isOpenedFromXBees(): boolean`
+
+Returns `true` when the integration is running inside an x-bees iFrame or a React Native WebView. Returns `false` in standalone/dev mode; all `send*` calls will be no-ops in that case.
+
+#### `isVisible(): boolean`
+
+Returns `true` when the UI iFrame is currently active (visible to the user). Updated automatically via the `VISIBILITY` event.
+
+---
+
+### UI state and launch mode
+
+#### `showsUi(): boolean`
+
+Returns `true` for all modes that render UI (`ui`, `d`, `f`). Opposite of `isDataOnly()`.
+
+#### `isDataOnly(): boolean`
+
+Returns `true` when the integration is launched in `no-ui` or `daemon` mode (no UI rendered).
+
+#### `isSetupDialog(): boolean`
+
+Returns `true` when the integration is launched in dialog/setup mode (`d` or `dialog`).
+
+#### `isFullsize(): boolean`
+
+Returns `true` when the integration is launched in fullsize mode (`f`).
+
+#### `isActivationOnly(): boolean`
+
+Returns `true` when the integration is opened for activation/authorization purposes only (URL contains the `authorize` parameter).
+
+---
+
+### Context
+
+#### `getContext(): Promise<ResponseMessage>`
+
+Retrieves the current x-bees context data. The shape of the payload depends on the active context (e.g. contact view, conversation view).
+
+#### `getCurrentContact(): Promise<ResponseMessage>`
+
+Retrieves the contact data currently open in x-bees.
+
+#### `getCurrentConversation(): Promise<ResponseMessage>`
+
+Retrieves the conversation data (`{ id, type }`) currently open in x-bees. Resolves with `undefined` payload if the conversation is temporary.
+
+#### `getAvailableContactData(): Promise<ResponseMessage>`
+
+Retrieves contact data that x-bees has available for the current context (phone numbers, emails, etc.). Useful to pre-populate integration forms.
+
+---
+
+### Theme
+
+#### `getThemeMode(): Promise<ResponseMessage>`
+
+Retrieves the current theme mode (`'light'` or `'dark'`).
+
+#### `getTheme(): Promise<ResponseMessage>`
+
+Retrieves the full theme object including mode and theme options (typography, palette).
 
-Sends the message to x-bees that user actions are required:
+#### `onThemeChange(callback: (theme: IPayloadThemeChange) => void): RemoveEventListener`
 
-### Contacts search
+Starts listening for theme-change events. Invokes `callback` whenever the user changes the x-bees theme. Returns an unsubscribe function.
 
-#### `onSuggestContacts: ((query: string, resolve: Resolve, reject: Reject) => void) => RemoveEventListener`
+---
 
-Starts listen for the events of searching contacts and handle autosuggestion with the provided callback */
+### Token
 
-```jsx
+#### `getXBeesToken(): Promise<ResponseMessage>`
+
+Requests the current x-bees authentication token from x-bees. Use this when you need the token for API calls to x-bees services.
+
+#### `onPbxTokenChange(callback: (token: string) => void): RemoveEventListener`
+
+Starts listening for PBX token change events. Invokes `callback` with the new token value. Returns an unsubscribe function.
+
+---
+
+### Calls
+
+#### `startCall(phoneNumber: string): Promise<ResponseMessage>`
+
+Sends a request to x-bees to initiate a call to the given phone number.
+
+#### `onCallStarted(callback: (info: IPayloadCallStartedInfo) => void): RemoveEventListener`
+
+Starts listening for the event fired when a call starts. Returns an unsubscribe function.
+
+#### `onCallEnded(callback: () => void): RemoveEventListener`
+
+Starts listening for the event fired when a call ends. Returns an unsubscribe function.
+
+---
+
+### Contacts
+
+#### `contactUpdated(query: ContactQuery, contact: Contact): Promise<ResponseMessage>`
+
+Notifies x-bees that a contact was created or updated. `query` identifies the contact (`{ id?, email?, phone? }`); `contact` contains the updated data.
+
+#### `contactMatchUpdated(query: ContactQuery, contact: Contact): Promise<ResponseMessage>`
+
+Notifies x-bees that a contact match was updated. Used when the integration resolves a contact lookup initiated by x-bees.
+
+#### `onSuggestContacts(callback: (query: string, resolve: SuggestContactsResolver, reject: Reject) => void): RemoveEventListener`
+
+Starts listening for contact auto-suggest requests from x-bees. When the user types in a contact search field, x-bees calls `callback` with the search string. Call `resolve(contacts)` to return results.
+
+```ts
 Client.getInstance().onSuggestContacts(async (query, resolve) => {
-    try {
-        const contacts = await fetchContacts(query);
-        resolve(contacts);
-    } catch (error) {
-        console.log('catch', error);
-    }
+  try {
+    const contacts = await fetchContacts(query);
+    resolve(contacts);
+  } catch (error) {
+    console.log('catch', error);
+  }
 });
 ```
 
-#### `onLookupAndMatchContact: ((query: ContactQuery, resolve: Resolve, reject: Reject) => void) => RemoveEventListener`
+#### `onLookupAndMatchContact(callback: (query: ContactQuery, resolve: LookupAndMatchContactsResolver, reject: Reject) => void): RemoveEventListener`
 
-Starts listen for the events of searching contact info and handle match with the provided callback
+Starts listening for single-contact lookup requests. x-bees supplies a `ContactQuery` and expects a single matched `Contact` via `resolve`.
 
-```jsx
+```ts
 Client.getInstance().onLookupAndMatchContact(async (query, resolve) => {
-    try {
-        const contact = await fetchContactAndMatch(query);
-        resolve(contact);
-    } catch (error) {
-        console.log('catch', error);
-    }
+  try {
+    const contact = await fetchContactAndMatch(query);
+    resolve(contact);
+  } catch (error) {
+    console.log('catch', error);
+  }
 });
 ```
 
-### Context
-#### `getContext(): Promise<Response>`
+#### `onLookupAndMatchBatchContacts(callback: (queries: ContactQuery[], returnResults: LookupAndMatchBatchContactsResolver) => void): RemoveEventListener`
 
-Retrieves current x-bees context data. The data may be different depending on context.
+Starts listening for batch contact lookup requests. x-bees sends an array of `ContactQuery` objects. Call `returnResults` with a `Map<ContactQuery, Contact | null | undefined>` mapping each query to its result.
 
-#### `getCurrentContact(): Promise<Response>`
+```ts
+Client.getInstance().onLookupAndMatchBatchContacts(async (queries, returnResults) => {
+  const resultsMap = new Map<ContactQuery, Contact | null>();
+  for (const query of queries) {
+    resultsMap.set(query, await fetchContact(query));
+  }
+  returnResults(resultsMap);
+});
+```
 
-Retrieves contact data currently opened in x-bees.
+#### `createContactIsSupported(): Promise<ResponseMessage>`
 
-#### `getCurrentConversation(): Promise<Response>`
+Sends a signal to x-bees indicating that this integration supports creating contacts. Call once during initialization if your integration handles contact creation.
 
-Retrieves conversation data ({id, type}) currently opened in x-bees.
-If the conversation is temporary - retrieves undefined
+#### `createContactHasNoPermission(): Promise<ResponseMessage>`
 
-#### `getThemeMode(): Promise<Response>`
+Sends a signal to x-bees indicating that the current user does not have permission to create contacts.
 
-Retrieves current theme mode (light or dark)
+---
 
-#### `getTheme(): Promise<Response>`
+### Navigation
 
-Retrieves current theme mode and theme options
+#### `onRedirectQuery(callback: Callback<EventType.REDIRECT_QUERY>): RemoveEventListener`
 
-#### `onThemeChange: (callback: ThemeChangeListenerCallback) => void;`
+Starts listening for redirect query events. Fires when the user opens the app via a deep-link that targets this integration. Returns an unsubscribe function.
 
-Starts to listen for the events of changing theme and returns the provided callback
+#### `onStartRedirectToEntityPage(callback: Callback<EventType.START_REDIRECT_TO_ENTITY_PAGE>): RemoveEventListener`
 
-#### `onPbxTokenChange: (callback: ListenerCallback) => void;`
+Starts listening for the event that signals x-bees is navigating to an entity page (e.g. conversation). The payload contains `{ conversationId, pageName }`. Returns an unsubscribe function.
 
-Starts to listen for the events of changing PBX token and returns the provided callback
+#### `onCancelRedirectToEntityPage(callback: Callback<EventType.CANCEL_REDIRECT_TO_ENTITY_PAGE>): RemoveEventListener`
 
-#### `onCallStarted: (callback: ListenerCallback) => void;`
+Starts listening for the event that signals a pending redirect to an entity page was cancelled. The payload contains `{ conversationId }`. Returns an unsubscribe function.
 
-Starts to listen for the events of starting the call and returns the provided callback
+---
 
-#### `onCallEnded: (callback: ListenerCallback) => void;`
+### Visibility and lifecycle
 
-Starts to listen for the events of ending the call and returns the provided callback
+#### `onVisibilityChange(callback: (isVisible: boolean) => void): RemoveEventListener`
 
-#### `off: (callback: ListenerCallback) => void;`
+Starts listening for iframe visibility changes. `callback` receives `true` when the iFrame becomes active and `false` when it is hidden. Returns an unsubscribe function.
 
-Removes particular callback from handling events
+#### `reboot(): Promise<ResponseMessage>`
 
+Sends a request to x-bees to restart the iFrame and reload it with the latest parameters and token.
 
-### Other
-#### `version(): string`
+#### `onLogout(callback: Callback<EventType.LOGOUT>): RemoveEventListener`
+
+Starts listening for the logout event. Notifies x-bees that the integration supports logout. `callback` is invoked when x-bees requests a logout action.
+
+---
+
+### Contact events
+
+#### `onContactWeightUpdate(callback: Callback<EventType.CONTACT_WEIGHT_UPDATE>): RemoveEventListener`
+
+Starts listening for contact weight update events. Fires when x-bees recalculates the relevance weight of a contact. The payload contains `{ id, query }`. Returns an unsubscribe function.
+
+#### `onContactRefresh(callback: Callback<EventType.CONTACT_REFRESH>): RemoveEventListener`
+
+Starts listening for contact refresh events. Fires when a contact was updated in the x-bees daemon and the open integration should re-fetch its data. Returns an unsubscribe function.
+
+---
+
+### UI utilities
+
+#### `showToast(message: string, severity?: ToastSeverity): Promise<ResponseMessage>`
+
+Displays a toast notification inside the x-bees UI. `severity` defaults to `'INFO'`. Accepted values: `'INFO'`, `'WARNING'`, `'ERROR'`, `'SUCCESS'`, `'NOTICE'`.
+
+```ts
+client.showToast('Contact saved', 'SUCCESS');
+```
+
+#### `setViewport(payload: { height: number | string; width: number | string }): Promise<ResponseMessage>`
 
-Retrieves the version of xBeesConnect
+Sends a request to x-bees to resize the iFrame to the specified dimensions.
 
-#### `startCall(phoneNumber: string)`
+#### `toClipboard(payload: string): Promise<ResponseMessage>`
 
-Sends a request to x-bees to start a call with a number
+Sends a request to x-bees to write the given string to the user's clipboard.
 
-#### `reboot()`
+---
 
-Sends a request to x-bees to restart the iFrame, reload with actual parameters and token
+### Event listeners (generic)
 
-#### `setViewport({height: number; width: number})`
+#### `addEventListener<T extends EventType>(eventName: T, callback: Callback<T>): RemoveEventListener`
 
-Sends a request to x-bees about changes of the current frame size
+Starts listening for any x-bees event by name. Returns an unsubscribe function. Prefer the typed convenience methods (`onThemeChange`, `onCallStarted`, etc.) when available.
 
-#### `toClipboard(payload: string)`
+#### `removeEventListener<T extends EventType>(eventName: T, callback: Callback<T>): void`
 
-Sends a request to x-bees to put a string to the user's clipboard
+Stops listening for the specified event with the given callback reference.
+
+#### `off(callback: Callback | StorageEventCallback): void`
+
+Removes the given callback from all event listeners, including local storage listeners registered via `onStorage`.
+
+---
+
+### Analytics
+
+#### `sendAnalytics(eventName: string, params?: Record<string, string>): void`
+
+Sends an analytics event to x-bees for tracking. `params` is an optional map of string key-value pairs.
+
+```ts
+client.sendAnalytics('contact_viewed', { contactId: '123' });
+```
+
+---
+
+### Local storage
+
+These methods read and write to the browser's `localStorage`, namespaced per integration.
+
+#### `saveToStorage<T>(key: string, value: T): void`
+
+Saves a value to `localStorage` under the given key. The value is serialized to JSON automatically.
+
+#### `getFromStorage<T>(key: string): T | null`
+
+Retrieves and deserializes a value from `localStorage`. Returns `null` if the key does not exist.
+
+#### `deleteFromStorage(key: string): void`
+
+Removes the entry with the given key from `localStorage`.
+
+#### `setIntegrationStorageKey(integrationKey: string): void`
+
+Switches the localStorage namespace to the specified parent integration key. Use this when the integration inherits storage from a parent integration.
+
+#### `onStorage(listener: StorageEventCallback): () => void`
+
+Registers a listener for `localStorage` change events (native `StorageEvent`). Returns an unsubscribe function.
+
+```ts
+const unsubscribe = client.onStorage((event) => {
+  console.log('Storage changed:', event.key, event.newValue);
+});
+```
+
+---
+
+### x-bees storage
+
+These methods persist data in x-bees' own server-side storage, not in the browser's `localStorage`. Data stored here survives browser clears and is available across devices.
+
+#### `saveInXbeesStorage<T>(key: string, value: T): void`
+
+Saves a value to the x-bees storage. The value is serialized to a JSON string before sending.
+
+#### `getFromXbeesStorage(key: string): Promise<ResponseMessage>`
+
+Requests a stored value from x-bees storage by key. Resolves with a `ResponseMessage` whose payload contains the stored value.
+
+#### `removeFromXbeesStorage(key: string): void`
+
+Removes the entry with the given key from x-bees storage.
+
+---
+
+### Custom events
+
+#### `sendCustomEvent({ type: string, payload?: JSONValue }): void`
+
+Sends a custom event to x-bees with an arbitrary `type` string and optional JSON-serializable payload. Use this for integration-specific communication not covered by the built-in event types.
+
+```ts
+client.sendCustomEvent({ type: 'my_action', payload: { foo: 'bar' } });
+```
 
-#### `addEventListener()`
+#### `sendDropdownVisibilityEvent(dropdownVisibilityStatus: boolean): void`
 
-Starts listening for one of the x-bees events and returns the provided callback
+> **Legacy:** prefer `sendCustomEvent` for new integrations.
 
-#### `removeEventListener()`
+Notifies x-bees when a dropdown inside the integration opens or closes, which allows x-bees to enable nested scrolling on Android WebView.
 
-Stops listening for one of the x-bees events with the particular callback
+---
 
-#### `onLogout()`
+### Technical support
 
-Starts listen on logout event and send event to the xbees about logout able
+#### `getTechnicalSupport(): TechnicalSupport`
 
-#### `sendAnalytics()`
+Returns the `TechnicalSupport` singleton, which provides utilities for reporting diagnostic information to x-bees support.
 
-Sends analytics data to xbees for track into analytics data
+---
 
 ## Known issues
 
@@ -178,6 +486,6 @@ The below function can fix cases when `String.replaceAll()` does not work in the
 
 ```ts
 function replaceAll(str: string, search: string, replace: string) {
-    return str.split(search).join(replace);
+  return str.split(search).join(replace);
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wildix/xbees-connect",
-  "version": "1.3.6",
+  "version": "1.3.7",
   "description": "This library provides easy communication between x-bees and integrated web applications",
   "author": "dimitri.chernykh <dimitri.chernykh@wildix.com>",
   "homepage": "",