feat(intercom): add support cordova-intercom v14+ (#4839)

* feat(intercom): update wrapper for Cordova Intercom v14+

* update types

* intercom: update types

* intercom: update types

* fix readme generator

src/@awesome-cordova-plugins/plugins/intercom/index.ts

@@ -5,7 +5,7 @@ import { Injectable } from '@angular/core';
  * @name Intercom
  * @description
  * This is a plugin that allows your Ionic app to use Intercom for iOS and/or Intercom for Android.
- * Follow the offical documentation to setup this plugin correctly: https://developers.intercom.com/docs/cordova-phonegap-configuration
+ * Follow the offical documentation to setup this plugin correctly: https://developers.intercom.com/installing-intercom/cordova-phonegap/installation
  * @usage
  * ```typescript
  * import { Intercom } from '@awesome-cordova-plugins/intercom/ngx';
@@ -31,196 +31,282 @@ import { Injectable } from '@angular/core';
 @Injectable()
 export class Intercom extends AwesomeCordovaNativePlugin {
   /**
-   * Register a identified user
+   * Login a user with identifiable information.
-   *
+   * Valid identifiers are `userId` and `email` which must be set in an object.
-   * @param options {any} Options
+   * @param options The object that contains the user's `email` or `userId`.
-   * @returns {Promise<any>} Returns a promise
    */
   @Cordova()
-  registerIdentifiedUser(options: any): Promise<any> {
+  loginUserWithUserAttributes(options: IntercomLoginUserAttributes): Promise<void> {
     return;
   }
 
   /**
-   * Register a unidentified user
+   * Login a unidentified user.
-   *
+   * This is a user that doesn't have any identifiable information such as a `userId` or `email`.
-   * @param options {any} Options
-   * @returns {Promise<any>} Returns a promise
    */
   @Cordova()
-  registerUnidentifiedUser(options: any): Promise<any> {
+  loginUnidentifiedUser(options: { [key: string]: number | string }): Promise<void> {
     return;
   }
 
   /**
-   * This resets the Intercom integration's cache of your user's identity and wipes the slate clean.
+   * Log a user out of their Intercom session.
-   *
+   * This will dismiss any Intercom UI and clear Intercom's local cache.
-   * @returns {Promise<any>} Returns a promise
    */
   @Cordova()
-  reset(): Promise<any> {
+  logout(): Promise<void> {
     return;
   }
 
   /**
+   * Set `hash` string if you are using Identity Verification for your Intercom workspace.
+   * @note This should be called before any user login takes place.
    *
-   * @returns {Promise<any>} Returns a promise
+   * Identity Verification helps to make sure that conversations between you and your users are kept private, and that one
+   * user can't impersonate another. If Identity Verification is enabled for your app, Intercom will sign all requests
+   * going to the Intercom servers with tokens. It requires your mobile application to have its own server which authenticates the app's users,
+   * and which can store a secret.
+   *
+   * @see More information on Identity Verification can be found {@link https://developers.intercom.com/installing-intercom/cordova-phonegap/identity-verification/ here}
+   * @param secureHash A HMAC digest of the user ID or email.
    */
   @Cordova()
-  logout(): Promise<any> {
+  setUserHash(secureHash: string): Promise<void> {
     return;
   }
 
   /**
+   * Update a user in Intercom with data specified in an object.
    *
-   * @param secureHash {string}
+   * @param attributes The object with the user data.
-   * @param secureData {any}
-   * @returns {Promise<any>} Returns a promise
-   * @deprecated Use setUserHash instead as of Intercom Cordova 4.0.0 and higher https://github.com/intercom/intercom-cordova/blob/master/CHANGELOG.md#400-2017-08-29
    */
   @Cordova()
-  setSecureMode(secureHash: string, secureData: any): Promise<any> {
+  updateUser(attributes: IntercomUserAttributes): Promise<void> {
     return;
   }
 
   /**
+   * Log an event with a given name and metaData.
+   * You can log events in Intercom based on user actions in your app.
    *
-   * @param secureHash {string}
+   * @param eventName The name of the event.
-   * @returns {Promise<any>} Returns a promise
+   * @param metaData Metadata Objects support a few simple types that Intercom can present on your behalf,
+   * @see https://developers.intercom.com/docs/references/rest-api/api.intercom.io/Data-Events/data_event/ Intercom API docs
    */
   @Cordova()
-  setUserHash(secureHash: string): Promise<any> {
+  logEvent(eventName: string, metaData: IntercomEventMetaData): Promise<void> {
     return;
   }
 
   /**
-   *
+   * Present Intercom as a modal overlay in your app.
-   * @param attributes {any}
+   * The `Home` space is displayed by default.
-   * @returns {Promise<any>} Returns a promise
    */
   @Cordova()
-  updateUser(attributes: any): Promise<any> {
+  present(): Promise<void> {
     return;
   }
 
   /**
+   * Present an Intercom `space` as a modal overlay in your app
+   * @see {@link Space} for a list of valid spaces.
    *
-   * @param eventName {string}
+   * @param space The Intercom space to be presented.
-   * @param metaData {any}
-   * @returns {Promise<any>} Returns a promise
    */
   @Cordova()
-  logEvent(eventName: string, metaData: any): Promise<any> {
+  presentSpace(space: IntercomSpace): Promise<void> {
     return;
   }
 
   /**
+   * Present Intercom content.
    *
-   * @returns {Promise<any>} Returns a promise
+   * An IntercomContent object.
    */
   @Cordova()
-  displayMessenger(): Promise<any> {
+  presentContent(content: IntercomPresentContent): Promise<void> {
     return;
   }
 
   /**
+   * Present the message composer.
    *
-   * @returns {Promise<any>} Returns a promise
+   * @param initialMessage An optional message that is used to pre-populate the composer with some text.
    */
   @Cordova()
-  displayMessageComposer(): Promise<any> {
+  presentMessageComposer(initialMessage: string): Promise<void> {
     return;
   }
 
   /**
+   * Fetch all Help Center collections.
    *
-   * @param initialMessage {string}
+   * @return An array of HelpCenterCollection objects.
-   * @returns {Promise<any>} Returns a promise
    */
   @Cordova()
-  displayMessageComposerWithInitialMessage(initialMessage: string): Promise<any> {
+  fetchHelpCenterCollections(): Promise<IntercomHelpCenterCollectionContent[]> {
     return;
   }
 
   /**
+   * Fetch the contents of a Help Center collection.
    *
-   * @returns {Promise<any>} Returns a promise
+   * @param collectionId The ID of the Help Center collection.
+   *
+   * @return A HelpCenterCollectionContent object.
    */
   @Cordova()
-  displayConversationsList(): Promise<any> {
+  fetchHelpCenterCollection(collectionId: string): Promise<IntercomHelpCenterCollectionContent> {
     return;
   }
 
   /**
+   * Search the Help Center.
    *
-   * @returns {Promise<any>} Returns a promise
+   * @param searchTerm The search term.
+   *
+   * @return An array of HelpCenterArticleSearchResult objects.
    */
   @Cordova()
-  displayHelpCenter(): Promise<any> {
+  searchHelpCenter(searchTerm: string): Promise<IntercomHelpCenterArticleSearchResult> {
     return;
   }
 
   /**
-   *
+   * Fetch the current number of unread conversations for the logged in User.
-   * @returns {Promise<any>} Returns a promise
+   * @return The number of unread conversations.
    */
   @Cordova()
-  unreadConversationCount(): Promise<any> {
+  unreadConversationCount(): Promise<number> {
     return;
   }
 
   /**
+   * Show or hide the Intercom Launcher in your app.
+   * @note The Launcher is hidden by default.
    *
-   * @param visibility {string}
+   * @param visibility A boolean indicating if the Intercom Launcher should be visible.
-   * @returns {Promise<any>} Returns a promise
    */
   @Cordova()
-  setLauncherVisibility(visibility: string): Promise<any> {
+  setLauncherVisibility(visibility: IntercomVisibility): Promise<void> {
     return;
   }
 
   /**
+   * Show or hide the Intercom InApp Messages in your app.
+   * @note All InApp Messages are visible by default.
    *
-   * @param visibility {string}
+   * @param visibility A boolean indicating if the InApps should be visible.
-   * @returns {Promise<any>} Returns a promise
    */
   @Cordova()
-  setInAppMessageVisibility(visibility: string): Promise<any> {
+  setInAppMessageVisibility(visibility: IntercomVisibility): Promise<void> {
     return;
   }
 
   /**
-   *
+   * Hide all Intercom windows that are currently displayed.
-   * @returns {Promise<any>} Returns a promise
+   * This will hide the Messenger, Help Center, Articles, and in-product messages (eg. Mobile Carousels, chats, and posts).
    */
   @Cordova()
-  hideMessenger(): Promise<any> {
+  hideIntercom(): Promise<void> {
     return;
   }
 
   /**
-   *
+   * Set a fixed bottom padding for in app messages and the Intercom Launcher.
-   * @returns {Promise<any>} Returns a promise
+   * @param bottomPadding The size of the bottom padding in points.
    */
   @Cordova()
-  registerForPush(): Promise<any> {
+  setBottomPadding(bottomPadding: number): Promise<void> {
     return;
   }
 
   /**
-   *
+   * Register for push notifications
-   * @param token {string}
+   * @note This function is only available for iOS.
-   * @returns {Promise<any>} Returns a promise
    */
   @Cordova()
-  sendPushTokenToIntercom(token: string): Promise<any> {
+  registerForPush(): Promise<void> {
     return;
   }
 
   /**
+   * Send a device token to Intercom to enable push notifications to be sent to the User.
+   * @param token The device token to send to the server.
    *
-   * @param carouselId {string}
+   * @note This function is only available for Android.
-   * @returns {Promise<any>} Returns a promise
+   */
+  @Cordova()
+  sendPushTokenToIntercom(token: string): Promise<void> {
+    return;
+  }
+
+  /**
+   * @deprecated
+   */
+  @Cordova()
+  registerIdentifiedUser(options: any): Promise<void> {
+    return;
+  }
+
+  /**
+   * @deprecated
+   */
+  @Cordova()
+  registerUnidentifiedUser(options: any): Promise<void> {
+    return;
+  }
+
+  /**
+   * @deprecated
+   */
+  @Cordova()
+  reset(): Promise<void> {
+    return;
+  }
+
+  /**
+   * @deprecated
+   */
+  @Cordova()
+  displayMessenger(): Promise<void> {
+    return;
+  }
+
+  /**
+   * @deprecated
+   */
+  @Cordova()
+  displayHelpCenter(): Promise<void> {
+    return;
+  }
+
+  /**
+   * @deprecated
+   */
+  @Cordova()
+  displayMessageComposerWithInitialMessage(initialMessage: string): Promise<void> {
+    return;
+  }
+
+  /**
+   * @deprecated
+   */
+  @Cordova()
+  displayMessageComposer(): Promise<void> {
+    return;
+  }
+
+  /**
+   * @deprecated
+   */
+  @Cordova()
+  displayHelpCenterCollections(collectionIds: string[]): Promise<any> {
+    return;
+  }
+
+  /**
+   * @deprecated
    */
   @Cordova()
   displayCarousel(carouselId: string): Promise<any> {
@@ -228,9 +314,7 @@ export class Intercom extends AwesomeCordovaNativePlugin {
   }
 
   /**
-   *
+   * @deprecated
-   * @param articleId {string}
-   * @returns {Promise<any>} Returns a promise
    */
   @Cordova()
   displayArticle(articleId: string): Promise<any> {
@@ -238,22 +322,80 @@ export class Intercom extends AwesomeCordovaNativePlugin {
   }
 
   /**
-   *
+   * @deprecated
-   * @param bottomPadding {string | number}
-   * @returns {Promise<any>} Returns a promise
-   */
-  @Cordova()
-  setBottomPadding(bottomPadding: string | number): Promise<any> {
-    return;
-  }
-
-  /**
-   * Programmatically display a Survey
-   * @param surveyId {string}
-   * @returns {Promise<any>} Returns a promise
    */
   @Cordova()
   displaySurvey(surveyId: string): Promise<any> {
     return;
   }
 }
+
+export enum IntercomVisibility {
+  VISIBLE = 'VISIBLE',
+  GONE = 'GONE',
+}
+
+export enum IntercomSpace {
+  Home = 'HOME',
+  HelpCenter = 'HELP_CENTER',
+  Messages = 'MESSAGES',
+  Tickets = 'TICKETS',
+}
+
+export interface IntercomHelpCenterCollectionContent {
+  collectionId: string;
+  title: string;
+  summary: string;
+  articles: any[];
+  sections: any[];
+}
+
+export enum IntercomPresentContentType {
+  Article = 'ARTICLE',
+  Carousel = 'CAROUSEL',
+  Survey = 'SURVEY',
+  HelpCenterCollections = 'HELP_CENTER_COLLECTIONS',
+  Conversation = 'CONVERSATION',
+}
+
+export type IntercomPresentContent =
+  | { id: string; type: IntercomPresentContentType }
+  | { ids: string[]; type: IntercomPresentContentType };
+
+export interface IntercomUserAttributes {
+  email?: string;
+  user_id?: string;
+  name?: string;
+  phone?: string;
+  language_override?: string;
+  signed_up_at?: string;
+  unsubscribed_from_emails?: string;
+  custom_attributes?: string;
+  companies?: string[];
+}
+
+export interface IntercomEventMetaData {
+  created_at: string;
+  type?: string;
+  metadata?: any;
+  [key: string]: number | string | { [key: string]: number | string };
+}
+
+export type IntercomLoginUserAttributes =
+  | {
+      email: string;
+    }
+  | {
+      userId: string;
+    }
+  | {
+      email: string;
+      userId: string;
+    };
+
+export interface IntercomHelpCenterArticleSearchResult {
+  articleId: string;
+  title: string;
+  summary: string;
+  matchingSnippet: string;
+}