Improved webhook notification support (#102)

# Description
This PR improves the support for webhook notifications. There are now
two new classes representing notification attributes for event and job
status notifications. There are also new fields for event metadata
visibility, and a new enum representing Job Status actions
(`JobStatus.Action`).

There is another improvement planned for webhook notification in the
next major release:

1. `Notification.Attributes` will be turned into an interface, and
classes like `EventNotificationAttributes` and
`JobStatusNotificationAttributes` will implement `Attributes`. The
current contents of `Attributes` will be moved into another class that
will also implement `Attributes`.
2. `Notification.MessageTrackingData` will be abstracted and split into
smaller classes with fields specific to corresponding webhook
notifications.

because these changes are breaking changes, it will not be implemented
until the next major version.

# License
<!-- Your PR comment must contain the following line for us to merge the
PR. -->
I confirm that this contribution is made under the terms of the MIT
license and that I have the authority necessary to make this
contribution on behalf of its copyright owner.

Author: mrashed-dev

CHANGELOG.md

@@ -6,6 +6,8 @@ This section contains changes that have been committed but not yet released.
 
 ### Added
 
+* Improved webhook notification support with the addition of more notification attributes and event metadata fields
+
 ### Changed
 
 * NylasAccount.revokeAccessToken() returns a boolean value now

src/main/java/com/nylas/JobStatus.java

@@ -1,5 +1,8 @@
 package com.nylas;
 
+import com.squareup.moshi.Json;
+import com.squareup.moshi.adapters.EnumJsonAdapter;
+
 import java.util.Map;
 
 public class JobStatus extends AccountOwnedModel {
@@ -9,6 +12,51 @@ public class JobStatus extends AccountOwnedModel {
 	private String object;
 	private String status;
 	private Map<String, Object> metadata;
+
+	/** Known actions for job status */
+	public enum Action {
+		@Json(name="create_calendar")
+		CREATE_CALENDAR,
+		@Json(name="update_calendar")
+		UPDATE_CALENDAR,
+		@Json(name="delete_calendar")
+		DELETE_CALENDAR,
+		@Json(name="create_contact")
+		CREATE_CONTACT,
+		@Json(name="update_contact")
+		UPDATE_CONTACT,
+		@Json(name="delete_contact")
+		DELETE_CONTACT,
+		@Json(name="create_folder")
+		CREATE_FOLDER,
+		@Json(name="update_folder")
+		UPDATE_FOLDER,
+		@Json(name="delete_folder")
+		DELETE_FOLDER,
+		@Json(name="create_label")
+		CREATE_LABEL,
+		@Json(name="update_label")
+		UPDATE_LABEL,
+		@Json(name="create_event")
+		CREATE_EVENT,
+		@Json(name="update_event")
+		UPDATE_EVENT,
+		@Json(name="delete_event")
+		DELETE_EVENT,
+		@Json(name="update_message")
+		UPDATE_MESSAGE,
+		@Json(name="save_draft")
+		SAVE_DRAFT,
+		@Json(name="new_outbox")
+		NEW_OUTBOX,
+
+		UNKNOWN;
+
+		@Override
+		public String toString() {
+			return super.toString().toLowerCase();
+		}
+	}
 
 	public String getAction() {
 		return action;
@@ -76,5 +124,11 @@ public String toString() {
 	static class JobStatusJson {
 
 	}
-	
+
+	/**
+	 * Adapter for deserializing job actions as enums.
+	 * Actions from the API that are not matched returns {@link Action#UNKNOWN}
+	 */
+	public static final EnumJsonAdapter<Action> JOB_STATUS_ACTIONS_ADAPTER =
+			EnumJsonAdapter.create(Action.class).withUnknownFallback(Action.UNKNOWN);
 }

src/main/java/com/nylas/JsonHelper.java

@@ -23,16 +23,22 @@ public class JsonHelper {
 
 	static {
 		moshi = new Moshi.Builder()
+				// Polymorphic adapters
 				.add(Event.WHEN_JSON_FACTORY)
 				.add(Event.EVENT_NOTIFICATION_JSON_FACTORY)
         		.add(Delta.ACCOUNT_OWNED_MODEL_JSON_FACTORY)
+				// Custom adapters
 				.add(new NeuralCategorizer.CategorizeCustomAdapter())
 				.add(new Integration.IntegrationCustomAdapter())
 				.add(new Integration.IntegrationListCustomAdapter())
 				.add(new Grant.GrantCustomAdapter())
 				.add(new Grant.GrantListCustomAdapter())
 				.add(new LoginInfo.LoginInfoCustomAdapter())
+				.add(new Notification.WebhookDeltaAdapter())
+				// Date adapters
 				.add(Date.class, new Rfc3339DateJsonAdapter().nullSafe())
+				// Enum adapters
+				.add(JobStatus.Action.class, JobStatus.JOB_STATUS_ACTIONS_ADAPTER)
 				.build();
 	}
 

src/main/java/com/nylas/Notification.java

@@ -1,15 +1,21 @@
 package com.nylas;
 
+import java.io.IOException;
 import java.nio.charset.StandardCharsets;
 import java.security.GeneralSecurityException;
 import java.time.Instant;
 import java.util.Arrays;
 import java.util.List;
+import java.util.Map;
 
 import javax.crypto.Mac;
 import javax.crypto.spec.SecretKeySpec;
 
+import com.squareup.moshi.FromJson;
+import com.squareup.moshi.Json;
 import com.squareup.moshi.JsonAdapter;
+import com.nylas.JobStatus.Action;
+import com.squareup.moshi.JsonReader;
 
 public class Notification {
 
@@ -98,8 +104,8 @@ public static class ObjectData {
 		private String object;
 		private String account_id;
 		private String id;
-		private Attributes attributes;
 		private MessageTrackingData metadata;
+		private transient Attributes attributes;
 
 		/**
 		 * The type of the object that triggered this notification
@@ -146,7 +152,14 @@ public String toString() {
 		}
 
 	}
-	
+
+	/**
+	 * Attributes for a message notification
+	 * <br>
+	 * Note: In the next major release Attributes will become an interface,
+	 * and this class will become "MessageNotificationAttributes" extending
+	 * from Attributes
+	 */
 	public static class Attributes {
 		private String received_date;
 		private String thread_id;
@@ -170,10 +183,160 @@ public String toString() {
 			return "Attributes [receivedDate=" + received_date + ", threadId=" + thread_id + "]";
 		}
 	}
+
+	/**
+	 * Attributes for event notifications
+	 */
+	public static class EventNotificationAttributes extends Attributes {
+		private String calendar_id;
+		private Boolean created_before_account_connection;
+
+		/**
+		 * Calendar ID of the event
+		 */
+		public String getCalendarId() {
+			return calendar_id;
+		}
+
+		/**
+		 * Indicates if the event was created before the account was connected to Nylas
+		 */
+		public Boolean getCreatedBeforeAccountConnection() {
+			return created_before_account_connection;
+		}
+
+		@Override
+		public String toString() {
+			return "EventNotificationAttributes [calendarId=" + calendar_id + ", createdBeforeAccountConnection=" + created_before_account_connection + "]";
+		}
+	}
+
+	/**
+	 * Attributes for job status notifications
+	 */
+	public static class JobStatusNotificationAttributes extends Attributes {
+		private Action action;
+		private String message_id;
+		private String job_status_id;
+		private Extras extras;
+
+		/**
+		 * Event that triggered the job status webhook
+		 */
+		public Action getAction() {
+			return action;
+		}
+
+		/**
+		 * ID of the message associated with the Job
+		 */
+		public String getMessageId() {
+			return message_id;
+		}
+
+		/**
+		 * ID of the job
+		 */
+		public String getJobStatusId() {
+			return job_status_id;
+		}
+
+		/**
+		 * If the job has a status of cancelled, delayed, or failed then extras will contain more information
+		 */
+		public Extras getExtras() {
+			return extras;
+		}
+
+		@Override
+		public String toString() {
+			return "JobStatusNotificationAttributes [action=" + action + ", threadId=" + getThreadId() + ", messageId="
+					+ message_id + ", jobStatusId=" + job_status_id + ", extras=" + extras + "]";
+		}
+
+		/**
+		 * Extra information in the event that a job was cancelled, delayed or failed
+		 */
+		public static class Extras {
+			private String reason;
+			private Long send_at;
+			private Long original_send_at;
+
+			/**
+			 * Reason for status
+			 */
+			public String getReason() {
+				return reason;
+			}
+
+			/**
+			 * Unix timestamp for when the message was sent
+			 */
+			public Instant getSendAt() {
+				return Instants.toNullableInstant(send_at);
+			}
+
+			/**
+			 * Unix timestamp assigned from sending a message
+			 */
+			public Instant getOriginalSendAt() {
+				return Instants.toNullableInstant(original_send_at);
+			}
+
+			@Override
+			public String toString() {
+				return "Extras [reason=" + reason + ", sendAt=" + getSendAt() + ", originalSendAt=" + getOriginalSendAt() + "]";
+			}
+		}
+	}
+
+	/**
+	 * This adapter identifies the type of object this notification is for,
+	 * and deserializes it to the appropriate Attributes class.
+	 */
+	@SuppressWarnings("unchecked")
+	static class WebhookDeltaAdapter {
+		@FromJson
+		Delta fromJson(JsonReader reader, JsonAdapter<Delta> delegate) throws IOException {
+			Map<String, Object> json = JsonHelper.jsonToMap(reader);
+			Delta delta = delegate.fromJson(JsonHelper.mapToJson(json));
+			if(delta != null && delta.object_data != null) {
+				Map<String, Object> objectDataJson = (Map<String, Object>) json.get("object_data");
+				if(objectDataJson.get("attributes") != null) {
+					Map<String, Object> attributesJson = (Map<String, Object>) objectDataJson.get("attributes");
+					if(attributesJson != null) {
+						if(delta.object != null) {
+							Class<? extends Attributes> attributeClass;
+							switch(delta.object) {
+								case "event":
+									attributeClass = EventNotificationAttributes.class;
+									break;
+								case "job_status":
+									attributeClass = JobStatusNotificationAttributes.class;
+									break;
+								case "message":
+								default:
+									attributeClass = Attributes.class;
+							}
+							delta.object_data.attributes = JsonHelper
+								.moshi()
+								.adapter(attributeClass)
+								.fromJson(JsonHelper.mapToJson(attributesJson));
+						}
+					}
+				}
+			}
+
+			return delta;
+		}
+	}
 
-	/*
-	 * Perhaps this class could be better served by splitting into subclasses for specific
-	 * notification types.  Not sure it's worth the time investment yet to get the Moshi JSON parsing done.
+	/**
+	 * Metadata for webhook notifications
+	 * <br>
+	 * Note: In the next major release this class will be split into
+	 * smaller classes more specific to the different types of metadata
+	 * depending on the type of webhook notification
 	 */
 	public static class MessageTrackingData {
 		private String message_id;
@@ -192,6 +355,11 @@ public static class MessageTrackingData {
 		// message.link_clicked specific fields
 		private List<LinkClickCount> link_data;
 		private List<LinkClick> recents;  // also in message.opened
+
+		// event specific fields
+		@Json(name = "event-type")
+		private String eventType;
+		private String message;
 
 		/**
 		 * Nylas message ID for the tracked message
@@ -283,12 +451,30 @@ public List<LinkClick> getRecentClicks() {
 			return recents;
 		}
 
+		/**
+		 * The custom event type set for the Event
+		 *
+		 * Available for event notifications only
+		 */
+		public String getEventType() {
+			return eventType;
+		}
+
+		/**
+		 * The custom message set for the Event
+		 *
+		 * Available for event notifications only
+		 */
+		public String getMessage() {
+			return message;
+		}
+
 		@Override
 		public String toString() {
 			return "MessageTrackingData [messageId=" + message_id + ", senderAppId=" + sender_app_id + ", payload="
 					+ payload + ", timestamp=" + getTimestamp() + ", threadId=" + thread_id + ", fromSelf=" + from_self
 					+ ", replyToMessageId=" + reply_to_message_id + ", openedCount=" + count + ", linkClickCounts="
-					+ link_data + ", recentClicks=" + recents + "]";
+					+ link_data + ", recentClicks=" + recents + ", eventType=" + eventType + ", message=" + message + "]";
 		}
 	}