@acrobits/ipc-sdk 0.10.0 → 0.11.2-alpha.0

package/lib/index.d.ts

@@ -3,11 +3,57 @@
  *
  * @public
  */
-export declare interface BaseContactItem {
+export declare type BaseContactItem = {
+    /**
+     * Unique ID for the contact item.
+     *
+     * @remarks
+     * This value is required since v2.1.
+     *
+     * @since 2.1
+     */
+    contactId?: string;
     /**
      * Type of contact item.
      */
     type: ContactType;
+    /**
+     * Cloud ID associated with the contact.
+     *
+     * @deprecated Use {@link CloudContact.cloudId} instead.
+     */
+    cloudId?: string;
+    /**
+     * Network ID for the contact.
+     *
+     * @deprecated Use {@link CloudContact.networkId} instead.
+     */
+    networkId?: string;
+};
+
+/**
+ * @deprecated Use unified DetailedContactItem instead
+ */
+declare type BaseDetailedContactItem = {
+    type: 'cloudUsername' | 'uri';
+    contactId?: string;
+    cloudId: string;
+    networkId: string;
+    displayName?: string;
+    profilePictureUrl?: string;
+};
+
+/**
+ * Defines cloud-username contact information.
+ *
+ * @public
+ * @since 2.1
+ */
+declare type CloudContact = {
+    /**
+     * Cloud username associated with the contact.
+     */
+    cloudUsername: string;
     /**
      * Cloud ID associated with the contact.
      */
@@ -16,27 +62,55 @@ export declare interface BaseContactItem {
      * Network ID for the contact.
      */
     networkId: string;
-}
+};
 
 /**
  * Defines the properties of a CloudUsername based contact item.
  *
  * @public
  */
-export declare interface CloudUsernameContactItem extends BaseContactItem {
+export declare type CloudUsernameContactItem = BaseContactItem & {
     type: 'cloudUsername';
+    /**
+     * Cloud user associated with the contact.
+     *
+     * @since 2.1
+     */
+    contactUser: CloudContact;
     /**
      * Cloud username associated with the contact.
+     *
+     * @deprecated Use {@link CloudContact.cloudUsername} instead.
      */
+    cloudUsername?: string;
+};
+
+/**
+ * @deprecated Use unified DetailedContactItem instead
+ */
+declare type CloudUsernameDetailedContactItem = BaseDetailedContactItem & {
+    type: 'cloudUsername';
     cloudUsername: string;
-}
+};
+
+/**
+ * Defines an email for a contact item.
+ *
+ * @example
+ * ```ts
+ * const email1 = 'test@example.com';
+ * const email2 = 'test@example.com';
+ *
+ * @public
+ */
+declare type ContactEmail = `${string}@${string}`;
 
 /**
- * Represents either a CloudUsername or Sip URI based contact item.
+ * Represents either a CloudUsername, Number or Sip URI based contact item.
  *
  * @public
  */
-export declare type ContactItem = CloudUsernameContactItem | UriContactItem;
+export declare type ContactItem = CloudUsernameContactItem | UriContactItem | NumberContactItem | EmailContactItem;
 
 /**
  * Label of contact being described.
@@ -45,12 +119,25 @@ export declare type ContactItem = CloudUsernameContactItem | UriContactItem;
  */
 export declare type ContactLabel = 'home' | 'work' | 'mobile' | 'other';
 
+/**
+ * Defines a number for a contact item. Number should be in E.164 format.
+ *
+ * @example
+ * ```ts
+ * const number1 = '1234567890';
+ * const number2 = '+1234567890';
+ * ```
+ *
+ * @public
+ */
+declare type ContactNumber = `${number}` | `+${number}`;
+
 /**
  * Defines a basic Contact Item type.
  *
  * @public
  */
-export declare type ContactType = 'cloudUsername' | 'uri';
+export declare type ContactType = 'cloudUsername' | 'uri' | 'number' | 'email';
 
 /**
  * Defines a URI for a contact item.
@@ -63,35 +150,46 @@ export declare type ContactType = 'cloudUsername' | 'uri';
  *
  * @public
  */
-export declare type ContactURI = `sip:${string}` | `tel:${string}` | `sips:${string}` | `tels:${string}`;
+export declare type ContactURI = `sip:${string}` | `tel:${ContactNumber}` | `sips:${string}` | `tels:${ContactNumber}`;
 
 /**
- * Defines a {@link DetailedContactItem} object with additional fields like profile picture,
- * SIP URIs and contact type etc.
+ * Defines an email and its associated label.
  *
  * @public
+ * @since 2.1
  */
-export declare interface DetailedContactItem {
+declare type DetailedContactEmail = {
     /**
-     * Type of contact item.
+     * Email associated with the contact.
      */
-    type: ContactType;
+    email: ContactEmail;
     /**
-     * Cloud ID associated with the contact.
+     * Label associated with this email.
      */
-    cloudId: string;
-    /**
-     * Cloud username associated with the contact.
-     */
-    cloudUsername: string;
-    /**
-     * Network ID for the contact.
-     */
-    networkId: string;
+    label: ContactLabel;
+};
+
+/**
+ * Defines a unified contact item with all possible contact methods.
+ * At least one contact method (contactUser, uri, or numbers) should be defined.
+ *
+ * @remarks
+ * This is a unified type that replaces the previous union type of different contact subtypes.
+ * For backward compatibility, the contactId field is optional but it is required since v2.1.
+ *
+ * @public
+ * @since 2.1
+ */
+export declare type DetailedContactItem = {
     /**
-     * URI or number associated with the contact with prefix (e.g. sip: or tel:)
+     * Unique ID for the contact item.
+     *
+     * @remarks
+     * This value is required since v2.1.
+     *
+     * @since 2.1
      */
-    uri: ContactURI | DetailedContactURI[];
+    contactId?: string;
     /**
      * Name of the contact entry.
      */
@@ -100,16 +198,49 @@ export declare interface DetailedContactItem {
      * An optional URL for the contact's profile picture.
      */
     profilePictureUrl?: string;
-}
+    /**
+     * Cloud contact information.
+     * Contains cloudUsername, cloudId, and networkId.
+     */
+    contactUser?: CloudContact;
+    /**
+     * URIs associated with the contact.
+     */
+    uri?: DetailedContactURI[];
+    /**
+     * Numbers associated with the contact.
+     */
+    numbers?: DetailedContactNumber[];
+    /**
+     * Emails associated with the contact.
+     */
+    emails?: DetailedContactEmail[];
+};
 
 /**
- * Defines a SIP URI and it's associated label.
+ * Defines a number and its associated label.
+ *
+ * @public
+ */
+declare type DetailedContactNumber = {
+    /**
+     * Number associated with the contact.
+     */
+    number: ContactNumber;
+    /**
+     * Label associated with this number.
+     */
+    label: ContactLabel;
+};
+
+/**
+ * Defines a SIP URI and its associated label.
  *
  * @public
  */
 export declare interface DetailedContactURI {
     /**
-     * URI or number associated with the contact with prefix (e.g. sip: or tel:)
+     * URI associated with the contact with prefix (e.g. sip: or tel:)
      */
     uri: ContactURI;
     /**
@@ -118,6 +249,19 @@ export declare interface DetailedContactURI {
     label: ContactLabel;
 }
 
+/**
+ * Defines the properties of an email based contact item.
+ *
+ * @public
+ */
+declare type EmailContactItem = BaseContactItem & {
+    type: 'email';
+    /**
+     * Email associated with the contact.
+     */
+    emails: ContactEmail[];
+};
+
 /**
  * Type of the Host app. Valid values are only `webrtc`, `desktop`, `ios`, `android`, `ios_jitsi`
  * and `electron`.
@@ -169,7 +313,11 @@ export declare const enum IPCEvents {
     /**
      * Event that is fired when the `Host` app sends a new PUSH TOKEN.
      */
-    PushToken = "PUSH TOKEN"
+    PushToken = "PUSH TOKEN",
+    /**
+     * Event that is fired when the `Host` app sends a REQUEST LOGS event.
+     */
+    RequestLogs = "REQUEST LOGS"
 }
 
 /**
@@ -238,6 +386,21 @@ export declare class IPCManager {
     /**
      * Requests the `Host` app to open the contact selection UI.
      *
+     * @param corelationId - An identifier for the message stream
+     * @param options - Configuration options for contact selection:
+     *   - `mode`: Whether to allow 'single' or 'multi' contact selection
+     *   - `currentContacts`: For multi-select mode, the list of currently selected contacts
+     *   - `contactType`: The type of contacts to select ('cloudUsername' or 'uri'). Defaults to 'cloudUsername'
+     *   - `includeOffNetworkContacts`: Whether to include contacts not on the network. Defaults to false
+     *
+     * @returns A collection of {@link ContactItem} objects which the user selected
+     */
+    selectContacts(corelationId: number, options: SelectContactsOptions): Promise<ContactItem[]>;
+    /**
+     * Requests the `Host` app to open the contact selection UI.
+     *
+     * @deprecated Use the `selectContacts` method with the `options` parameter instead.
+     *
      * @remarks
      * When requesting a `single` contact, the `Host` app will return immediately
      * after contact selection.
@@ -254,6 +417,8 @@ export declare class IPCManager {
     /**
      * Requests the `Host` app to open the contact selection UI.
      *
+     * @deprecated Use the `selectContacts` method with the `options` parameter instead.
+     *
      * @remarks
      * When requesting a `multi` contact, the user will have to manually close the contact selection
      * UI. The `Host` app will return the selected contacts when the user closes the UI.
@@ -272,6 +437,8 @@ export declare class IPCManager {
      * `corelationId`.
      */
     selectContacts(corelationId: number, mode: 'multi', currentContacts: ContactItem[], contactType?: ContactType): Promise<ContactItem[]>;
+    private selectContacts_V2_0;
+    private selectContacts_V2_1;
     /**
      * Matches batch of {@link ContactItem} objects against the Host's contact list to fetch detailed
      * contact information.
@@ -281,7 +448,7 @@ export declare class IPCManager {
      * @returns A collection of {@link DetailedContactItem} objects which were matched against the
      * Host's contact list.
      */
-    matchContacts(contacts: ContactItem[]): Promise<DetailedContactItem[]>;
+    matchContacts(contacts: ContactItem[]): Promise<Record<string, DetailedContactItem | null | undefined> | CloudUsernameDetailedContactItem[]>;
     /**
      * Requests the `Host` app to provide the Push Token for the current device.
      *
@@ -309,6 +476,25 @@ export declare class IPCManager {
      * @remarks
      * Any additional data to be posted alongside the URL is included with the `data` parameter.
      *
+     * @example
+     *
+     * ```ts
+     * // import the IPCManager
+     * import { IPCManager } from '@acrobits/ipc-sdk';
+     *
+     * // create an instance of IPCManager
+     * const manager = new IPCManager();
+     *
+     * // open the URL with additional data
+     * const url = 'https://example.com';
+     * const data = {
+     *   name: 'John Doe',
+     *   age: 30
+     * };
+     *
+     * manager.openUrl(url, data);
+     * ```
+     *
      * @param url - URL to open in the external browser
      * @param data - _Optional_. Any additional data to be sent along with the URL
      */
@@ -352,6 +538,22 @@ export declare class IPCManager {
      * @returns An unsubscribe callback to remove the listener.
      */
     onPushToken(callback: (token: string, appId: string, selector: string) => void): () => boolean | undefined;
+    /**
+     * Registers a callback to be invoked when a {@link IPCEvents.RequestLogs} event is received.
+     *
+     * @remarks
+     * The Host app can request logs from the Client app by sending a RequestLogs event. The callback
+     * will receive a skipCompression parameter indicating whether the logs should be compressed or not.
+     *
+     * When skipCompression is true, the logs should be sent uncompressed. When false or undefined,
+     * the logs should be compressed before sending.
+     *
+     * @param callback - A callback function to be invoked when a {@link IPCEvents.RequestLogs} event
+     * is received. The callback receives an optional skipCompression parameter.
+     *
+     * @returns An unsubscribe callback to remove the listener.
+     */
+    onRequestLogsMessage(callback: (skipCompression?: boolean) => void): () => boolean | undefined;
     private evaluateContext;
 }
 
@@ -360,7 +562,26 @@ export declare class IPCManager {
  *
  * @public
  */
-export declare type IpcProtocolVersion = '0.1' | '0.2' | '0.3' | '0.4' | '0.5' | '0.6' | '0.7' | '0.8' | '0.9' | '0.10' | '2.0';
+export declare type IpcProtocolVersion = '0.1' | '0.2' | '0.3' | '0.4' | '0.5' | '0.6' | '0.7' | '0.8' | '0.9' | '0.10' | '2.0' | '2.1';
+
+/**
+ * Defines the properties of a number based contact item.
+ *
+ * @public
+ */
+declare type NumberContactItem = BaseContactItem & {
+    type: 'number';
+    /**
+     * Number associated with the contact.
+     */
+    numbers: ContactNumber[];
+};
+
+declare type SelectContactsOptions = {
+    mode: 'single' | 'multi';
+    currentContacts?: ContactItem[];
+    resultTypes?: ContactType[];
+};
 
 /**
  * A callback function to unsubscribe the registered listener.
@@ -374,12 +595,12 @@ export declare type UnsubscribeCallback = () => void;
  *
  * @public
  */
-export declare interface UriContactItem extends BaseContactItem {
+export declare type UriContactItem = BaseContactItem & {
     type: 'uri';
     /**
      * URI or number associated with the contact with prefix (e.g. sip: or tel:)
      */
     uri: ContactURI;
-}
+};
 
 export { }