Fix handling actions, Add event handling documentation guide

docs/general-api.md

@@ -13,7 +13,7 @@ Notifications.registerRemoteNotifications();
 ```
 
 ## getInitialNotification()
-This method returns a promise. If the app was launched by a push notification, this promise resolves to an object of type [Notification](http://localhost:3000/react-native-notifications/docs/notification-object). Otherwise, it resolves to undefined.
+This method returns a promise. If the app was launched by a push notification, this promise resolves to an object of type [Notification](notification-object). Otherwise, it resolves to undefined.
 
 ```js
 const notification: Notification = await Notifications.getInitialNotification();

docs/general-events.md

@@ -14,7 +14,7 @@ Notifications.events().registerRemoteNotificationsRegistered((event: Registered)
 ```
 
 ## registerNotificationReceived()
-Fired when a remote notification is received in foreground state. The handler will be invoked with an instance of [Notification](http://localhost:3000/react-native-notifications/docs/notification-object).
+Fired when a remote notification is received in foreground state. The handler will be invoked with an instance of [Notification](notification-object).
 Should call completion function on iOS, will be ignored on Android.
 
 ```js
@@ -27,7 +27,7 @@ Notifications.events().registerNotificationReceived((notification: Notification,
 ```
 
 ## registerRemoteNotificationOpened()
-Fired when a remote notification is opened from dead or background state. The handler will be invoked with an instance of [Notification](http://localhost:3000/react-native-notifications/docs/notification-object).
+Fired when a remote notification is opened from dead or background state. The handler will be invoked with an instance of [Notification](notification-object).
 Should call completion function on iOS, will be ignored on Android.
 
 ```js

docs/notification-object.md

@@ -6,6 +6,11 @@ sidebar_label: Notification
 
 Contains the payload data.
 
+- **`message`**- returns the notification's main message string.
+- **`sound`**- returns the sound string from the `aps` object.
+- **`badge`**- returns the badge count number from the `aps` object.
+- **`category`**- returns the category from the `aps` object (related to interactive notifications).
+- **`data`**- returns the data payload (additional info) of the notification.
 
 Example:
 ```js

docs/notifications-events.md

+---
+id: notifications-events
+title: Handling Notification Events
+sidebar_label: Events
+---
+
+## <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/f/fa/Apple_logo_black.svg/2000px-Apple_logo_black.svg.png" width=30/> iOS
+
+When a push notification is received by the device, the application can be in one of the following states:
+
+1. **Forground:** When the app is running and is used by the user right now; in this case, a `notificationReceived` event will be fired, do not forget to invoke `completion()` callback.
+
+Finally, when a notification is _opened_ by the device user (i.e. tapped-on), a `notificationOpened` event is fired, here as well you need to remember invoking `completion()` callback.
+
+Example:
+
+```javascript
+constructor() {
+    Notifications.events().registerNotificationReceived((notification: Notification, completion: (response: NotificationCompletion) => void) => {
+			console.log("Notification Received - Foreground", notification.data);
+
+			// Calling completion on iOS with `alert: true` will present the native iOS inApp notification.
+			completion({alert: true, sound: true, badge: false});
+		});
+
+    Notifications.events().registerRemoteNotificationOpened((notification: Notification, completion: () => void, action: NotificationActionResponse) => {
+			console.log("Notification opened by device user", notification.data);
+			console.log(`Notification opened with an action identifier: ${action.identifier} and response text: ${action.text}`);
+			completion();
+		});
+}
+```
+
+### Notification Object
+
+When you receive a push notification, you'll get an instance of [Notification](notification-object) object, contains the following methods:
+
+## Querying initial notification
+
+React-Native's [`PushNotificationsIOS.getInitialNotification()`](https://facebook.github.io/react-native/docs/pushnotificationios.html#getinitialnotification) allows for the async retrieval of the original notification used to open the App on iOS, but it has no equivalent implementation for Android.
+
+```javascript
+import {Notifications} from 'react-native-notifications';
+
+Notifications.getInitialNotification()
+  .then((notification) => {
+  		console.log("Initial notification was:", (notification ? notification.data : 'N/A'));
+	})  	
+  .catch((err) => console.error("getInitialNotifiation() failed", err));
+
+```
+
+> **Note**
+> 
+> Notifications are considered 'initial' under the following terms:
+
+> - User tapped on a notification, _AND_ -
+> - App was either not running at all ("dead" state), _OR_ it existed in the background with **no running activities** associated with it.

example/index.js

@@ -39,7 +39,7 @@ class NotificationsExampleApp extends Component {
   }
 
   requestPermissions() {
-    Notifications.ios.requestPermissions();
+    Notifications.registerRemoteNotifications();
   }
 
   setCategories() {

lib/ios/RNNotificationEventHandler.m

@@ -30,7 +30,7 @@
 
 - (void)didReceiveNotificationResponse:(UNNotificationResponse *)response completionHandler:(void (^)(void))completionHandler {
     [_store setActionCompletionHandler:completionHandler withCompletionKey:response.notification.request.identifier];
-    [RNEventEmitter sendEvent:RNNotificationOpened body:[RNNotificationParser parseNotification:response.notification]];
+    [RNEventEmitter sendEvent:RNNotificationOpened body:[RNNotificationParser parseNotificationResponse:response]];
 }
 
 @end

lib/src/Notifications.ts

@@ -56,7 +56,7 @@ export class NotificationsRoot {
   /**
    * getInitialNotification
    */
-  public getInitialNotification(): Promise<Notification> {
+  public getInitialNotification(): Promise<Notification | undefined> {
     return this.commands.getInitialNotification();
   }
 

lib/src/adapters/NativeEventsReceiver.ts

@@ -3,6 +3,7 @@ import {
   Registered, RegistrationError, RegisteredPushKit
 } from '../interfaces/NotificationEvents';
 import { Notification } from '../DTO/Notification';
+import { NotificationActionResponse } from '../interfaces/NotificationActionResponse';
 
 export class NativeEventsReceiver {
   private emitter: EventEmitter;
@@ -28,9 +29,10 @@ export class NativeEventsReceiver {
     return this.emitter.addListener('pushKitNotificationReceived', callback);
   }
 
-  public registerRemoteNotificationOpened(callback: (response: Notification, completion: () => void) => void): EmitterSubscription {
-    return this.emitter.addListener('notificationOpened', (payload, completion) => {
-      callback(new Notification(payload), completion);
+  public registerRemoteNotificationOpened(callback: (notification: Notification, completion: () => void, actionResponse?: NotificationActionResponse) => void): EmitterSubscription {
+    return this.emitter.addListener('notificationOpened', (response, completion) => {
+      const action = response.action ? new NotificationActionResponse(response.action) : undefined
+      callback(new Notification(response.notification), completion, action);
     });
   }
 

lib/src/commands/Commands.ts

@@ -9,7 +9,7 @@ export class Commands {
   constructor(
     private readonly nativeCommandsSender: NativeCommandsSender,
     private readonly uniqueIdProvider: UniqueIdProvider
-  ) {}
+  ) { }
 
   public postLocalNotification(notification: Notification, id?: number) {
     const notificationId: number = id ? id : this.uniqueIdProvider.generate();
@@ -17,9 +17,13 @@ export class Commands {
     return result;
   }
 
-  public async getInitialNotification(): Promise<Notification> {
+  public async getInitialNotification(): Promise<Notification | undefined> {
     return this.nativeCommandsSender.getInitialNotification().then((payload) => {
-      return new Notification(payload);
+      if (payload) {
+        return new Notification(payload);
+      }
+
+      return undefined;
     });
   }
 

lib/src/interfaces/NotificationActionResponse.ts

-export interface NotificationActionResponse {
+export class NotificationActionResponse {
   identifier: string;
-  text: string;
+  text?: string;
+
+  constructor(response: any) {
+    this.identifier = response.identifier;
+    this.text = response.text;
+  }
 }

website/i18n/en.json

@@ -45,6 +45,10 @@
         "title": "Notification object",
         "sidebar_label": "Notification"
       },
+      "notifications-events": {
+        "title": "Handling Notification Events",
+        "sidebar_label": "Events"
+      },
       "subscription": {
         "title": "Push Notifications Subscription",
         "sidebar_label": "Subscription"

website/sidebars.json

 {
   "docs": {
     "Installation": ["installation-ios", "installation-android"],
-    "Guides": ["subscription", "localNotifications"],
+    "Guides": ["subscription", "notifications-events", "localNotifications"],
     "Advanced": ["advanced-ios"]
   },
   "api": {