@acrobits/ipc-sdk 0.11.2-alpha.8 → 0.12.0-alpha.11

package/lib/index.d.ts

@@ -23,17 +23,83 @@ export declare type BaseContactItem = {
     /**
      * Cloud ID associated with the contact.
      *
-     * @deprecated Use {@link CloudContact.cloudId} instead.
+     * @deprecated Use `CloudContact.cloudId` instead.
      */
     cloudId?: string;
     /**
      * Network ID for the contact.
      *
-     * @deprecated Use {@link CloudContact.networkId} instead.
+     * @deprecated Use `CloudContact.networkId` instead.
      */
     networkId?: string;
 };
 
+/**
+ * Represents information about a single call.
+ *
+ * @public
+ */
+export declare interface CallInfoItem {
+    /**
+     * Unique identifier for the call.
+     */
+    callId: string;
+    /**
+     * Call event ID as tracked by the Host app.
+     */
+    eventId: number;
+    /**
+     * Optional group ID as tracked by the Host app, provided if the call is part of a group.
+     */
+    groupId?: string;
+    /**
+     * Current state of the call.
+     */
+    callState: CallState;
+    /**
+     * Optional timestamp (in seconds since epoch) when the call was established.
+     */
+    establishedDate?: number;
+    /**
+     * Information about the remote user in the call.
+     */
+    remoteUser: RemoteUser;
+    /**
+     * Whether the call is currently on hold.
+     */
+    isHeld: boolean;
+}
+
+/**
+ * Possible states of a call as tracked by the Host app.
+ *
+ * - `Unknown` - Default/initial state; call state cannot be determined.
+ * - `Trying` - Outgoing call: INVITE sent, waiting for provisional response.
+ * - `Ringing` - Outgoing call: remote party is ringing (180 Ringing received).
+ * - `Busy` - Outgoing call: called party is busy (486 response). Terminal, Failed.
+ * - `IncomingAnswered` - Incoming call: user answered, media setup in progress.
+ * - `IncomingTrying` - Incoming call: protocol-level setup in progress, user has not answered.
+ * - `IncomingRinging` - Incoming call: alerting the user (ringing locally). This is the initial
+ *   state for pushed incoming calls received from SIPIS.
+ * - `IncomingIgnored` - Incoming call: user explicitly ignored the call on call screen or silenced
+ *   the ringer.
+ * - `IncomingRejected` - Incoming call: user explicitly rejected. Terminal.
+ * - `IncomingMissed` - Incoming call: caller hung up or timed out before user answered. Terminal.
+ * - `Established` - Call connected: signaling/media session established; actual media may be
+ *   muted/on hold/one-way.
+ * - `Error` - Call failed due to RTP, transport, or logic error. Terminal, Failed.
+ * - `Unauthorized` - Authentication with server failed. Terminal, Failed.
+ * - `Terminated` - Call ended normally (BYE exchanged or clean hangup). Terminal.
+ * - `IncomingForwarded` - Incoming call: forwarded to another destination by user. Terminal.
+ * - `IncomingAnsweredElsewhere` - Incoming call: answered on another device (same account).
+ *   Terminal.
+ * - `RedirectedToAlternativeService` - Outgoing call: server redirected to alternative service
+ *   (3xx/location). Terminal.
+ *
+ * @public
+ */
+export declare type CallState = 'Unknown' | 'Trying' | 'Ringing' | 'Busy' | 'IncomingAnswered' | 'IncomingTrying' | 'IncomingRinging' | 'IncomingIgnored' | 'IncomingRejected' | 'IncomingMissed' | 'Established' | 'Error' | 'Unauthorized' | 'Terminated' | 'IncomingForwarded' | 'IncomingAnsweredElsewhere' | 'RedirectedToAlternativeService';
+
 /**
  * Defines cloud-username contact information.
  *
@@ -71,7 +137,7 @@ export declare type CloudUsernameContactItem = BaseContactItem & {
     /**
      * Cloud username associated with the contact.
      *
-     * @deprecated Use {@link CloudContact.cloudUsername} instead.
+     * @deprecated Use `CloudContact.cloudUsername` instead.
      */
     cloudUsername?: string;
 };
@@ -81,8 +147,9 @@ export declare type CloudUsernameContactItem = BaseContactItem & {
  *
  * @example
  * ```ts
- * const email1 = 'test@example.com';
- * const email2 = 'test@example.com';
+ * const email1 = 'test\@example.com';
+ * const email2 = 'test\@example.com';
+ * ```
  *
  * @public
  */
@@ -267,6 +334,18 @@ export declare interface ILogger {
     error(...args: any[]): void;
 }
 
+/**
+ * An error thrown when a parameter in the message payload is invalid.
+ *
+ * @public
+ */
+export declare class InvalidParameterError extends Error {
+    param: string;
+    value: unknown;
+    reason: string;
+    constructor(param: string, value: unknown, reason: string);
+}
+
 /**
  * Defines the context the web app is running under.
  *
@@ -300,7 +379,11 @@ export declare const enum IPCEvents {
     /**
      * Event that is fired when the `Host` app sends a REQUEST LOGS event.
      */
-    RequestLogs = "REQUEST LOGS"
+    RequestLogs = "REQUEST LOGS",
+    /**
+     * Event that is fired when the `Host` app sends a CALL INFO update.
+     */
+    CallInfo = "CALL INFO"
 }
 
 /**
@@ -369,6 +452,10 @@ export declare class IPCManager {
     /**
      * Requests the `Host` app to open the contact selection UI.
      *
+     * @remarks
+     * This overload requires protocol version 2.1 or higher. If the negotiated version
+     * is 2.0, an {@link UnsupportedVersionError} will be thrown.
+     *
      * @param corelationId - An identifier for the message stream
      * @param options - Configuration options for contact selection:
      *   - `mode`: Whether to allow 'single' or 'multi' contact selection
@@ -377,214 +464,271 @@ export declare class IPCManager {
      *   - `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.
-     *
-     * @param corelationId - An identifier for the message stream
-     * @param mode - _Optional_. Whether to allow `single` or `multi` contact selection.
-     * @param contactType - _Optional_. The type of contacts to be selected. This can be either
-     * `cloudUsername` or `uri`. Defaults to `cloudUsername`.
-     *
-     * @returns A collection of {@link ContactItem} objects which the user selected along with the
-     * `corelationId`.
-     */
-    selectContacts(corelationId: number, mode?: 'single', contactType?: ContactType): 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 `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.
-     *
-     * When requesting a `multi` contact, the `currentContacts` parameter is required. This will
-     * be used to highlight the contacts that are already selected.
-     *
-     * @param corelationId - An identifier for the message stream
-     * @param mode - Whether to allow `single` or `multi` contact selection.
-     * @param currentContacts - A list of {@link ContactItem} objects that are currently selected.
-     * This is used to highlight the current contacts from the selection UI.
-     * @param contactType - _Optional_. The type of contacts to be selected. This can be either
-     * `cloudUsername` or `uri`. Defaults to `cloudUsername`.
-     *
-     * @returns A collection of {@link ContactItem} objects which the user selected along with the
-     * `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.
-     *
-     * @param contacts - List of {@link ContactItem} collection to match against the Host's contact
-     * list.
-     * @returns A collection of {@link DetailedContactItem} objects which were matched against the
-     * Host's contact list.
-     */
-    matchContacts(contacts: ContactItem[]): Promise<Record<string, DetailedContactItem_2 | null | undefined> | CloudUsernameDetailedContactItem[]>;
-    /**
-     * Requests the `Host` app to provide the Push Token for the current device.
-     *
-     * @returns A promise with the Push Token as `string`.
-     */
-    requestPushToken(): Promise<string>;
-    /**
-     * Sends the current badge count to the `Host` app.
-     *
-     * @param count - The count to update the badge to.
-     * @param isActivity - _Optional_. Whether the update is for an activity instead of a badge.
-     */
-    badgeUpdate(count: number, isActivity?: boolean): void;
-    /**
-     * Requests the `Host` app to reset the app and log out the user.
-     *
-     * @remarks
-     * For added security, the Host can confirm the user's intention to reset the app by displaying
-     * a confirmation dialog. The user can decide to cancel the reset operation.
-     */
-    requestAppReset(): void;
-    /**
-     * Requests the `Host` app to open the given URL in an external browser.
-     *
-     * @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
-     */
-    openUrl<TData>(url: string, data?: TData): void;
-    /**
-     * Initiates a SIP call to the given {@link ContactItem}.
-     *
-     * @param contact - {@link ContactItem} for the callee.
-     */
-    sipCall(contact: ContactItem): void;
-    /**
-     * Registers a callback to be invoked when a {@link IPCEvents.BadgeQuery} is received.
-     *
-     * @param callback - A callback function to be invoked when a {@link IPCEvents.BadgeQuery} event
-     * is received.
-     * @returns An unsubscribe callback to remove the listener.
-     */
-    onBadgeQueryRequest(callback: () => void): UnsubscribeCallback;
-    /**
-     * Registers a callback to be invoked when a {@link IPCEvents.Lifecycle} event is received.
-     *
-     * @remarks
-     * The `eventName` and `payload` are defined by the `Host` app and can vary for each LIFECYCLE
-     * event. The payload can be an empty object for events without any additional data.
-     *
-     * @param callback - A callback function to be invoked when a {@link IPCEvents.Lifecycle} event
-     * is received.
-     *
-     * @returns An unsubscribe callback to remove the listener.
-     */
-    onLifecycleEvent(callback: (event: string, payload: Record<string, unknown>) => void): UnsubscribeCallback;
-    /**
-     * Registers a callback to be invoked when a {@link IPCEvents.PushToken} event is received.
-     *
-     * @remarks
-     * The `token`, `appId`, `selector` and `expiry` are defined by the `Host` app and can vary for
-     * each Push Token event.
-     *
-     * @param callback - A callback function to be invoked when a {@link IPCEvents.PushToken} event
-     * is received.
-     * @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;
-}
+     * @throws {@link UnsupportedVersionError} if the negotiated version is 2.0.
+         */
+     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.
+      *
+      * @param corelationId - An identifier for the message stream
+      * @param mode - _Optional_. Whether to allow `single` or `multi` contact selection.
+      * @param contactType - _Optional_. The type of contacts to be selected. This can be either
+      * `cloudUsername` or `uri`. Defaults to `cloudUsername`.
+      *
+      * @returns A collection of {@link ContactItem} objects which the user selected along with the
+      * `corelationId`.
+      */
+     selectContacts(corelationId: number, mode?: 'single', contactType?: ContactType): 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 `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.
+      *
+      * When requesting a `multi` contact, the `currentContacts` parameter is required. This will
+      * be used to highlight the contacts that are already selected.
+      *
+      * @param corelationId - An identifier for the message stream
+      * @param mode - Whether to allow `single` or `multi` contact selection.
+      * @param currentContacts - A list of {@link ContactItem} objects that are currently selected.
+      * This is used to highlight the current contacts from the selection UI.
+      * @param contactType - _Optional_. The type of contacts to be selected. This can be either
+      * `cloudUsername` or `uri`. Defaults to `cloudUsername`.
+      *
+      * @returns A collection of {@link ContactItem} objects which the user selected along with the
+      * `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.
+      *
+      * @param contacts - List of {@link ContactItem} collection to match against the Host's contact
+      * list.
+      * @returns A collection of {@link DetailedContactItem} objects which were matched against the
+      * Host's contact list.
+      */
+     matchContacts(contacts: ContactItem[]): Promise<Record<string, DetailedContactItem_2 | null | undefined> | CloudUsernameDetailedContactItem[]>;
+     /**
+      * Requests the `Host` app to provide the Push Token for the current device.
+      *
+      * @returns A promise with the Push Token as `string`.
+      */
+     requestPushToken(): Promise<string>;
+     /**
+      * Sends the current badge count to the `Host` app.
+      *
+      * @param count - The count to update the badge to.
+      * @param isActivity - _Optional_. Whether the update is for an activity instead of a badge.
+      */
+     badgeUpdate(count: number, isActivity?: boolean): void;
+     /**
+      * Requests the `Host` app to reset the app and log out the user.
+      *
+      * @remarks
+      * For added security, the Host can confirm the user's intention to reset the app by displaying
+      * a confirmation dialog. The user can decide to cancel the reset operation.
+      */
+     requestAppReset(): void;
+     /**
+      * Requests the `Host` app to open the given URL in an external browser.
+      *
+      * @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
+      */
+     openUrl<TData>(url: string, data?: TData): void;
+     /**
+      * Initiates a SIP call to the given {@link ContactItem}.
+      *
+      * @param contact - {@link ContactItem} for the callee.
+      */
+     sipCall(contact: ContactItem): void;
+     /**
+      * Registers a callback to be invoked when a {@link IPCEvents.BadgeQuery} is received.
+      *
+      * @param callback - A callback function to be invoked when a {@link IPCEvents.BadgeQuery} event
+      * is received.
+      * @returns An unsubscribe callback to remove the listener.
+      */
+     onBadgeQueryRequest(callback: () => void): UnsubscribeCallback;
+     /**
+      * Registers a callback to be invoked when a {@link IPCEvents.Lifecycle} event is received.
+      *
+      * @remarks
+      * The `eventName` and `payload` are defined by the `Host` app and can vary for each LIFECYCLE
+      * event. The payload can be an empty object for events without any additional data.
+      *
+      * @param callback - A callback function to be invoked when a {@link IPCEvents.Lifecycle} event
+      * is received.
+      *
+      * @returns An unsubscribe callback to remove the listener.
+      */
+     onLifecycleEvent(callback: (event: string, payload: Record<string, unknown>) => void): UnsubscribeCallback;
+     /**
+      * Registers a callback to be invoked when a {@link IPCEvents.PushToken} event is received.
+      *
+      * @remarks
+      * The `token`, `appId`, `selector` and `expiry` are defined by the `Host` app and can vary for
+      * each Push Token event.
+      *
+      * @param callback - A callback function to be invoked when a {@link IPCEvents.PushToken} event
+      * is received.
+      * @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;
+     /**
+      * Requests the current call information from the `Host` app.
+      *
+      * @remarks
+      * This method requires protocol version 2.2 or higher. If the negotiated version
+      * is lower, an {@link UnsupportedVersionError} will be thrown.
+      *
+      * @returns A promise with an array of {@link CallInfoItem} objects representing
+      * the current calls.
+      *
+      * @throws {@link UnsupportedVersionError} if the negotiated version is below 2.2.
+          */
+      requestCallInfo(): Promise<CallInfoItem[]>;
+      /**
+       * Registers a callback to be invoked when a {@link IPCEvents.CallInfo} event is received.
+       *
+       * @remarks
+       * The Host app sends CALL INFO updates when call state changes occur. This includes
+       * new calls, call state transitions, and call terminations.
+       *
+       * Note: This event is only available on protocol version 2.2 or higher. On lower versions,
+       * the callback will never be invoked.
+       *
+       * @param callback - A callback function to be invoked when a {@link IPCEvents.CallInfo} event
+       * is received. The callback receives an array of {@link CallInfoItem} objects.
+       *
+       * @returns An unsubscribe callback to remove the listener.
+       */
+      onCallInfo(callback: (calls: CallInfoItem[]) => void): UnsubscribeCallback;
+      private evaluateContext;
+     }
 
-/**
- * Supported versions of the IPC Protocol.
- *
- * @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' | '2.1' | '2.2';
+     /**
+      * Supported versions of the IPC Protocol.
+      *
+      * @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' | '2.1' | '2.2';
 
-/**
- * Defines the properties of a number based contact item.
- *
- * @public
- */
-declare type NumberContactItem = BaseContactItem & {
-    type: 'number';
-    /**
-     * Number associated with the contact.
-     */
-    numbers: ContactNumber[];
-};
+     /**
+      * 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';
-    filterToSelectedType: boolean;
-    currentContacts?: ContactItem[];
-    resultTypes?: ContactType[];
-};
+     /**
+      * Represents the remote user in a call.
+      *
+      * @public
+      */
+     export declare interface RemoteUser {
+         /**
+          * Display name of the remote user.
+          */
+         displayName: string;
+         /**
+          * Transport URI of the remote user.
+          */
+         transportUri: string;
+     }
 
-/**
- * A callback function to unsubscribe the registered listener.
- *
- * @public
- */
-export declare type UnsubscribeCallback = () => void;
+     declare type SelectContactsOptions = {
+         mode: 'single' | 'multi';
+         filterToSelectedType: boolean;
+         currentContacts?: ContactItem[];
+         resultTypes?: ContactType[];
+     };
 
-/**
- * Defines the properties of a SIP URI based contact item.
- *
- * @public
- */
-export declare type UriContactItem = BaseContactItem & {
-    type: 'uri';
-    /**
-     * URI or number associated with the contact with prefix (e.g. sip: or tel:)
-     */
-    uri: ContactURI;
-};
+     /**
+      * A callback function to unsubscribe the registered listener.
+      *
+      * @public
+      */
+     export declare type UnsubscribeCallback = () => void;
+
+     /**
+      * An error thrown when the protocol version being requested is not supported by the app or library.
+      *
+      * @public
+      */
+     export declare class UnsupportedVersionError extends Error {
+         version: IpcProtocolVersion | IpcProtocolVersion[];
+         constructor(version: IpcProtocolVersion | IpcProtocolVersion[], minVersion?: IpcProtocolVersion);
+     }
+
+     /**
+      * Defines the properties of a SIP URI based contact item.
+      *
+      * @public
+      */
+     export declare type UriContactItem = BaseContactItem & {
+         type: 'uri';
+         /**
+          * URI or number associated with the contact with prefix (e.g. sip: or tel:)
+          */
+         uri: ContactURI;
+     };
 
-export { }
+     export { }