@amazon-devices/expo-notifications 2.0.9000000000-rn-83

package/src/kepler/types/NotificationManagerTypes.ts

@@ -0,0 +1,508 @@
+/*
+ * Copyright 2024 Amazon.com, Inc. or its affiliates. All rights reserved.
+ *
+ * AMAZON PROPRIETARY/CONFIDENTIAL
+ *
+ * You may not use this file except in compliance with the terms and
+ * conditions set forth in the accompanying LICENSE.TXT file.
+ *
+ * THESE MATERIALS ARE PROVIDED ON AN "AS IS" BASIS. AMAZON SPECIFICALLY
+ * DISCLAIMS, WITH RESPECT TO THESE MATERIALS, ALL WARRANTIES, EXPRESS,
+ * IMPLIED, OR STATUTORY, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
+ */
+
+import NotificationContent from '../NotificationContent';
+
+/**
+ * @brief Id key for notification
+ *
+ */
+export class Uuid {
+  bytes: Array<number>;
+  constructor(id: Array<number>) {
+    if (id.length !== 16) {
+      throw new Error('Size of id should be 16');
+    }
+    this.bytes = id;
+  }
+}
+
+/**
+ * Describes a progress bar to be displayed in a notification.
+ * Progress must be less than or equal to max. Values must be greater than
+ * or equal to 0.
+ */
+export interface Progress {
+  /**
+   * Progress value of the task at the time of the call.
+   * This is how far into the task the progress is.
+   */
+  progress: number;
+
+  /**
+   * Max value of the progress bar
+   * Value doesn't need to be 100.
+   * Example: 9/25 files downloaded
+   */
+  max: number;
+}
+
+/**
+ * Describes the importance of a notification.
+ */
+export class Importance {
+  /**
+   * General information
+   * Example: weather update
+   */
+  static IMPORTANCE_MIN: string = 'MIN';
+
+  /**
+   * Non-time sensitive information
+   * Example: new movie recommendation
+   */
+  static IMPORTANCE_LOW: string = 'LOW';
+
+  /**
+   * Information relevant to the user, non-urgent
+   * Example: App download ready
+   */
+  static IMPORTANCE_NORMAL: string = 'NORMAL';
+
+  /**
+   * Time-Critical information
+   * Example: Alarm, phonecall
+   * @privilege 'com.amazon.permission.notification.importance_high
+   */
+  static IMPORTANCE_HIGH: string = 'HIGH';
+
+  /**
+   * Urgent notification that requires an action
+   * Example: remote disconnected, device heating up
+   * @privilege 'com.amazon.permission.notification.system
+   */
+  static IMPORTANCE_MAX: string = 'MAX';
+
+  /**
+   * Importance level set on creation of the
+   * importance object.
+   */
+  importance: string = Importance.IMPORTANCE_NORMAL;
+}
+
+/**
+ * Interface to define an extra property in a notification.
+ * These properties are hints to the renderer and there are no
+ * guarantees any particular key/value pair will be used when
+ * renderering the notification.
+ */
+export interface Extra {
+  /**
+   * Name of the extra property.
+   * Cannot be empty, limited to 128 bytes.
+   * Example: "videoUri"
+   */
+  name: string;
+
+  /**
+   * Value of the extra property.
+   * Cannot be empty, limited to 512 bytes.
+   * Example: "www.amazon.com"
+   */
+  value: string;
+}
+
+/**
+ * Used to group similar types of notifications from a single app. A channel
+ * is specific to the app that created it and is used
+ * All notifications in the channel have a shared level of importance.
+ * An example is grouping all order notifications from Amazon
+ * and marking them as 'High' importance.
+ */
+export interface Channel {
+  /**
+   * Id of the Notification Channel. Name
+   * is specified by user while creating the channel.
+   */
+  name: string;
+
+  /**
+   * Description of what notifications are in this channel.
+   */
+  description: string;
+
+  /**
+   * Uri of the app that this channel is associated with
+   */
+  appUri?: string;
+
+  /**
+   * Level of importance of the notifications
+   * in this channel.
+   */
+  importance: Importance;
+
+  /**
+   * Kind of notification. Used to describe different
+   * kinds of notifications from a standard one. Different kinds
+   * may contain extra pieces of content or preferred ways to display
+   * the notification
+   */
+  kind: any;
+}
+
+/**
+ * Interface to define the contents of a notification. Describes what
+ * information will be included in the displayed notification.
+ * Built by NotificationContentBuilder
+ */
+export interface INotificationContent {
+  /**
+   * Title of the notification. Brief overview
+   * of the notification. First line of text
+   */
+  title: string;
+
+  /**
+   * Description of the notification
+   * Line of text after the title.
+   */
+  description: string;
+
+  /**
+   * Footnote of the notification.
+   * Line of text after the footnote.
+   */
+  footnote?: string;
+
+  /**
+   * Channel of the notification
+   * Describes which channel the notification is grouped in.
+   */
+  channel: Channel;
+
+  /**
+   * Sets the apps/services that can be launched by the notification when
+   * interacted with. Targets will attempt to be launched on interaction.
+   * Only the first one is guaranteed to be launched.
+   */
+  launchTargets?: Array<any>;
+
+  /**
+   * Sets the icon uri of the notification. This is the normal icon
+   * to be displayed with the notification.
+   * Displayed as the icon of the notification.
+   * Example is 'https://m.media-amazon.com/rockstar.png'
+   */
+  iconUri: string;
+
+  /**
+   * Sets the small icon uri. Small instance of the icon to be displayed
+   * when the notification is small.
+   * Example is 'https://m.media-amazon.com/rockstarSmall.png'
+   */
+  smallIconUri?: string;
+
+  /**
+   * Sets the large icon uri of the notification. Optional param
+   * Large version of the icon to be the an additional image displayed
+   * in the notification
+   * Example is 'https://m.media-amazon.com/rockstarLarge.png'
+   */
+  largeIconUri?: string;
+
+  /**
+   * Progress of the notification
+   * Used if the notification has progress to
+   * inform the user about.
+   */
+  progress?: Progress;
+
+  /**
+   * Timeout of the notification
+   * Used to describe the how long before
+   * the notification is removed in seconds.
+   * Defaults to no timeout.
+   */
+  timeout?: number;
+
+  /**
+   * List of extra properties that are hints
+   * that the renderer may use to render the notification.
+   * There is no guarantee that these extras will be used
+   * by the renderer.
+   */
+  extras?: Array<Extra>;
+
+  /**
+   * Priority of the notification in the channel.
+   * Potentially used by renderer to determine priority of
+   * notifications to display within an app's channel.
+   * Default returns 0, higher value is higher priority.
+   */
+  priorityHint?: number;
+}
+
+/**
+ * Class to build the notification content. A notification
+ * requires a title, description, iconUri, and channel.
+ * built from: 'INotificationManager::makeNotificationContentBuilder()'
+ */
+export class NotificationContentBuilder {
+  private mTitle?: string;
+  private mDescription?: string;
+  private mFootnote?: string;
+  private mChannel?: Channel;
+  private mLaunchTargets?: Array<any>;
+  private mIconUri?: string;
+  private mSmallIconUri?: string;
+  private mLargeIconUri?: string;
+  private mProgress?: Progress;
+  private mTimeout?: number;
+  private mExtras?: Array<Extra>;
+  private mPriorityHint?: number;
+
+  /**
+   * Sets the title of the notification. This is the short overview of
+   * the notification.
+   *
+   * @param title Title of the notification. Required param
+   */
+  public title(title: string): NotificationContentBuilder {
+    this.mTitle = title;
+    return this;
+  }
+
+  /**
+   * Sets the description of the notification. This is the main content of
+   * the notification. Required param
+   *
+   * @param description Description of the notification.
+   */
+  public description(description: string): NotificationContentBuilder {
+    this.mDescription = description;
+    return this;
+  }
+
+  /**
+   * Sets the footnote of the notification
+   *
+   * @param footnote Footnote of the notification. Optional param
+   */
+  public footnote(footnote: string): NotificationContentBuilder {
+    this.mFootnote = footnote;
+    return this;
+  }
+
+  /**
+   * Sets the icon uri of the notification. This is the normal icon
+   * to be displayed with the notification.
+   * Displayed as the icon of the notification.
+   * Example is 'https://m.media-amazon.com/rockstar.png'
+   *
+   * @param iconUri Icon uri for the notification. Required param
+   */
+  public iconUri(iconUri: string): NotificationContentBuilder {
+    this.mIconUri = iconUri;
+    return this;
+  }
+
+  /**
+   * Sets the small icon uri. Small instance of the icon to be displayed
+   * when the notification is small.
+   * Example is 'https://m.media-amazon.com/rockstarSmall.png'
+   *
+   * @param iconUri small icon uri. Optional param
+   */
+  public smallIconUri(smallIconUri: string): NotificationContentBuilder {
+    this.mSmallIconUri = smallIconUri;
+    return this;
+  }
+
+  /**
+   * Sets the large icon uri of the notification. Optional param
+   * Large version of the icon to be the an additional image displayed
+   * in the notification
+   * Example is 'https://m.media-amazon.com/rockstarLarge.png'
+   *
+   * @param iconUri Large Icon Uri of the notification
+   */
+  public largeIconUri(largeIconUri: string): NotificationContentBuilder {
+    this.mLargeIconUri = largeIconUri;
+    return this;
+  }
+
+  /**
+   * Sets the channel this notification will be associated with. Required param
+   * @param channel Channel the notification is associated with
+   */
+  public channel(channel: Channel): NotificationContentBuilder {
+    this.mChannel = channel;
+    return this;
+  }
+
+  /**
+   * Sets how long a notification will exist before being removed.
+   * Timeout value is in seconds. Notifications with the timeout value
+   * set to 0 or a negative values will not be automatically removed
+   * Optional param
+   */
+  public timeout(timeout: number): NotificationContentBuilder {
+    this.mTimeout = timeout;
+    return this;
+  }
+
+  /**
+   * Sets the priority of the notification in its channel. Used as a hint
+   * for how the renderer should prioritize displaying notifications in the
+   * channel. Optional param
+   * @param priority How important is the notification among other
+   * notifications in its channel.
+   */
+  public priorityHint(priorityHint: number): NotificationContentBuilder {
+    this.mPriorityHint = priorityHint;
+    return this;
+  }
+
+  /**
+   * Sets the values for a progress bar in the notification. Optional param
+   * Updated using the update function
+   */
+  public progress(progress: Progress): NotificationContentBuilder {
+    this.mProgress = progress;
+    return this;
+  }
+
+  /**
+   * Sets an array of extra properties/hints for the renderer.
+   * These extras have no guarantee of being used.
+   * Limited to 512 extras in array. Optional param
+   */
+  public extras(extras: Array<Extra>): NotificationContentBuilder {
+    this.mExtras = extras;
+    return this;
+  }
+
+  /**
+   * Sets the apps/services that can be launched by the notification when
+   * interacted with.
+   * Optional param
+   */
+  public launchTargets(launchTargets: Array<any>): NotificationContentBuilder {
+    this.mLaunchTargets = launchTargets;
+    return this;
+  }
+
+  /**
+   * Builds the immutable notification content instance.
+   * Finalizes the INotificationContent object and returns an
+   * instance.
+   * @throws Error if the required params aren't set
+   */
+  public build(): NotificationContent {
+    if (this.mTitle === undefined) {
+      throw Error('Missing Title');
+    }
+    if (this.mDescription === undefined) {
+      throw Error('Missing Description');
+    }
+    if (this.mIconUri === undefined) {
+      throw Error('Missing IconUri');
+    }
+    if (this.mChannel === undefined) {
+      throw Error('Missing Channel');
+    }
+    return new NotificationContent(
+      this.mTitle,
+      this.mDescription,
+      this.mFootnote,
+      this.mChannel,
+      this.mLaunchTargets,
+      this.mIconUri,
+      this.mSmallIconUri,
+      this.mLargeIconUri,
+      this.mProgress,
+      this.mTimeout,
+      this.mPriorityHint,
+      this.mExtras
+    );
+  }
+}
+
+/**
+ * Used to correlate the notification content with the
+ * id generated from posting the content
+ */
+export interface Notification {
+    /**
+     * Content of the notification
+     */
+    notificationContent: NotificationContent;
+
+    /**
+     * The id of the notification
+     */
+    id: Uuid;
+}
+
+enum kindDescriptor {
+  KIND,
+  ACTION_REQUIRED,
+  INFORMATION,
+  ON_GOING,
+  SYSTEM,
+  TOAST,
+}
+
+/**
+ * Class describing the base Kind. Kinds are used to
+ * describe the notification. Kinds may include extra properties
+ * relevant only to their kind.
+ */
+export class NotificationKind {
+  kindDescriptor: kindDescriptor = kindDescriptor.KIND;
+
+  /**
+   * Used to visit the 'kind' in a type safe way
+   * @param visitor Implementation of a visitor
+   * implementing functions that perform different tasks
+   * depending on the type of 'kind'
+   */
+  visit(visitor: any): any {
+    visitor.visitUnknown(this);
+  }
+}
+
+/**
+ * Kind used to indicate this is an information notification
+ * Information notifications are notifications to provide
+ * information to the user.
+ */
+export class InformationKind extends NotificationKind {
+  kindDescriptor: kindDescriptor = kindDescriptor.INFORMATION;
+
+  /**
+   * Returns true if the notification should be displayed
+   * on top of the foreground app.
+   * example: SMS notification
+   */
+  isImportant: boolean = false;
+
+  /**
+   * Returns true if the notification is immediately relevant
+   * to the app currently being displayed.
+   * Example: Uploading items failed
+   */
+  isShowIfAppDisplayed: boolean = false;
+
+  /**
+   * Used to visit the 'kind' in a type safe way
+   * @param visitor Implementation of a visitor
+   * implementing functions that perform different tasks
+   * depending on the type of 'kind'
+   */
+  visit(visitor: any): any {
+    visitor.visitInformation(this);
+  }
+}

package/src/kepler/types/index.ts

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2024 Amazon.com, Inc. or its affiliates. All rights reserved.
+ *
+ * AMAZON PROPRIETARY/CONFIDENTIAL
+ *
+ * You may not use this file except in compliance with the terms and
+ * conditions set forth in the accompanying LICENSE.TXT file.
+ *
+ * THESE MATERIALS ARE PROVIDED ON AN "AS IS" BASIS. AMAZON SPECIFICALLY
+ * DISCLAIMS, WITH RESPECT TO THESE MATERIALS, ALL WARRANTIES, EXPRESS,
+ * IMPLIED, OR STATUTORY, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
+ */
+
+export type { Channel, Extra, INotificationContent, Progress } from './NotificationManagerTypes';
+export { Importance, InformationKind, Uuid } from './NotificationManagerTypes';

package/src/presentNotificationAsync.ts

@@ -0,0 +1,32 @@
+import { UnavailabilityError, uuid } from 'expo-modules-core';
+
+import NotificationPresenter from './NotificationPresenterModule';
+import { NotificationContentInput } from './Notifications.types';
+
+let warningMessageShown = false;
+
+/**
+ * Schedules a notification for immediate trigger.
+ * @param content An object representing the notification content.
+ * @param identifier
+ * @return It returns a Promise resolving with the notification's identifier once the notification is successfully scheduled for immediate display.
+ * @header schedule
+ * @deprecated This method has been deprecated in favor of using an explicit `NotificationHandler` and the [`scheduleNotificationAsync`](#notificationsschedulenotificationasyncrequest) method. More information can be found in our [FYI document](https://expo.fyi/presenting-notifications-deprecated).
+ */
+export default async function presentNotificationAsync(
+  content: NotificationContentInput,
+  identifier: string = uuid.v4()
+): Promise<string> {
+  if (__DEV__ && !warningMessageShown) {
+    console.warn(
+      '`presentNotificationAsync` has been deprecated in favor of using `scheduleNotificationAsync` + an explicit notification handler. Read more at https://expo.fyi/presenting-notifications-deprecated.'
+    );
+    warningMessageShown = true;
+  }
+
+  if (!NotificationPresenter.presentNotificationAsync) {
+    throw new UnavailabilityError('Notifications', 'presentNotificationAsync');
+  }
+
+  return await NotificationPresenter.presentNotificationAsync(identifier, content);
+}

package/src/registerTaskAsync.ts

@@ -0,0 +1,39 @@
+import { UnavailabilityError } from 'expo-modules-core';
+
+// @amznmod_react - Changed .native import to one without postfix
+import BackgroundNotificationTasksModule from './BackgroundNotificationTasksModule';
+
+/**
+ * When a notification is received while the app is backgrounded, using this function you can set a callback that will be run in response to that notification.
+ * Under the hood, this function is run using `expo-task-manager`. You **must** define the task first, with [`TaskManager.defineTask`](./task-manager#taskmanagerdefinetasktaskname-taskexecutor).
+ * Make sure you define it in the global scope.
+ *
+ * The callback function you define with `TaskManager.defineTask` will receive an object with the following fields:
+ * - `data`: The remote payload delivered by either FCM (Android) or APNs (iOS). See [`PushNotificationTrigger`](#pushnotificationtrigger) for details.
+ * - `error`: The error (if any) that occurred during execution of the task.
+ * - `executionInfo`: JSON object of additional info related to the task, including the `taskName`.
+ * @param taskName The string you passed to `TaskManager.defineTask` as the `taskName` parameter.
+ *
+ * @example
+ * ```ts
+ * import * as TaskManager from '@amazon-devices/expo-task-manager';
+ * import * as Notifications from '@amazon-devices/expo-notifications';
+ *
+ * const BACKGROUND_NOTIFICATION_TASK = 'BACKGROUND-NOTIFICATION-TASK';
+ *
+ * TaskManager.defineTask(BACKGROUND_NOTIFICATION_TASK, ({ data, error, executionInfo }) => {
+ *   console.log('Received a notification in the background!');
+ *   // Do something with the notification data
+ * });
+ *
+ * Notifications.registerTaskAsync(BACKGROUND_NOTIFICATION_TASK);
+ * ```
+ * @header inBackground
+ */
+export default async function registerTaskAsync(taskName: string): Promise<null> {
+  if (!BackgroundNotificationTasksModule.registerTaskAsync) {
+    throw new UnavailabilityError('Notifications', 'registerTaskAsync');
+  }
+
+  return await BackgroundNotificationTasksModule.registerTaskAsync(taskName);
+}