Merge pull request #13 from Karn/develop

**New features**:
- Notification Alerting -- configure the LED color, sounds and vibrations of Notifications.
- Set the `LargeIcon`.
- Configure the People associated with the notification, this helps the system prioritize notifications and bypass Do Not Disturb mode if applicable.

**Breaking changes**:
- Modified:
    - `NotifyCreator#alerting(Payload.Alert.() -> Unit)` -> `NotifyCreator#alerting(String, Payload.Alert.() -> Unit)`
    - `Notify#defaultConfig { }` now uses DSL syntax for default `Header` and Alerting configuration.
- Renamed:
    - `Creator` -> `NotifyCreator`
    - `Notify#DEFAULT_CHANNEL_KEY` -> `Notify#CHANNEL_DEFAULT_KEY`
    - `Notify#DEFAULT_CHANNEL_NAME` -> `Notify#CHANNEL_DEFAULT_NAME`
    - `Notify#DEFAULT_CHANNEL_DESCRIPTION` -> `Notify#CHANNEL_DEFAULT_DESCRIPTION`

README.md

@@ -13,9 +13,9 @@ Simplified notification delivery for Android.
 
 
 #### GETTING STARTED
-You can install Notify using Jitpack while it is still in development.
+Notify (pre-)releases are available via JitPack. It is recommended that  a specific release version is selected when using the library in production as there may be breaking changes at anytime.
 
-As such there currently are pre-releases available until test coverage is improved.
+> **Tip:** Test out the canary channel to try out features by using the latest develop snapshot; `develop-SNAPSHOT`.
 
 ``` Groovy
 // Project level build.gradle
@@ -27,8 +27,8 @@ repositories {
 
 // Module level build.gradle
 dependencies {
-    // -SNAPSHOT (latest release)
-    implementation "io.karn:notify:-SNAPSHOT"
+    // Replace version with release version, e.g. 1.0.0-alpha, -SNAPSHOT
+    implementation "io.karn:notify:[VERSION]"
 }
 ```
 
@@ -48,7 +48,11 @@ Notify
 
 ![Basic usecase](./docs/assets/default.svg)
 
-If you run into a case in which the library does not provide the requisite builder functions you can get the `NotificationCompat.Builder` object and continue to use it as you would normally by calling `Creator#asBuilder()`.
+If you run into a case in which the library does not provide the requisite builder functions you can get the `NotificationCompat.Builder` object and continue to use it as you would normally by calling `NotifyCreator#asBuilder()`.
+
+> **Tip:** You can view other notification styles on the [Notification Types](./docs/types.md) docs page.
+
+> **Tip:** Advanced usage topics are documented [here](./docs/advanced.md).
 
 #### NOTIFICATION ANATOMY
 
@@ -61,8 +65,8 @@ If you run into a case in which the library does not provide the requisite build
 | 3    | Header Text  | Optional description text. Set using the `Header#headerText` field.                                     |
 | 4    | Timestamp    | Timestamp of the notification.                                                                          |
 | 5    | Expand Icon  | Indicates that the notification is expandable.                                                          |
-| 6    | Content      | The "meat" of the notification set using of of the `Creator#as[Type]((Type) -> Unit)` scoped functions. |
-| 7    | Actions      | Set using the `Creator#actions((ArrayList<Action>) -> Unit)` scoped function.                           |
+| 6    | Content      | The "meat" of the notification set using of of the `NotifyCreator#as[Type]((Type) -> Unit)` scoped functions. |
+| 7    | Actions      | Set using the `NotifyCreator#actions((ArrayList<Action>) -> Unit)` scoped function.                           |
 
 #### CONTRIBUTING
 There are many ways to [contribute](./.github/CONTRIBUTING.md), you can

build.gradle

@@ -18,7 +18,7 @@ buildscript {
     }
 
     dependencies {
-        classpath 'com.android.tools.build:gradle:3.2.0-alpha07'
+        classpath 'com.android.tools.build:gradle:3.2.0-alpha14'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
 
         // NOTE: Do not place your application dependencies here; they belong
@@ -39,5 +39,5 @@ allprojects {
 }
 
 task wrapper(type: Wrapper) {
-    gradleVersion = '4.5'
+    gradleVersion = '4.6'
 }

docs/advanced.md

@@ -0,0 +1,10 @@
+## Advanced Usage
+> **Note:** This page is still a work-in-progress. You can help complete the documentation by contributing to the project.
+
+
+#### RESPONDING TO CLICKS
+The `Payload.Meta` object provides `clickIntent` and `clearIntent` members which when not `null` will be fired when clicked or dismissed. 
+
+#### STACKABLE NOTIFICATIONS
+
+#### ACTIONS

docs/types.md

@@ -0,0 +1,120 @@
+## Notification Types
+
+#### STANDARD NOTIFICATION
+
+![Standard Notification](./assets/types/default.svg)
+
+Simple notifications are very easy!
+
+```Kotlin
+Notify
+    .with(context)
+    .content { // this: Payload.Content.Default
+        // The title of the notification (first line).
+        title = "New dessert menu"
+        // The second line of the notification.
+        text = "The Cheesecake Factory has a new dessert for you to try!"
+    }
+    .show()
+```
+
+#### LIST NOTIFICATION
+
+![List Notification](./assets/types/list-text.svg)
+
+Notifications with multiple lines are very common. Notify provides a simple DSL to build these notfications.
+
+```Kotlin
+Notify
+    .with(context)
+    .asTextList { // this: Payload.Content.TextList
+        // The lines that are shown when the notification is expanded.
+        lines = Arrays.asList("New! Fresh Strawberry Cheesecake.",
+                              "New! Salted Caramel Cheesecake.",
+                              "New! OREO Dream Dessert.")
+        // The title of the collapsed notification.
+        title = "New menu items!"
+        // The second line of the collapsed notification.
+        text = lines.size.toString() + " new dessert menu items found."
+    }
+    .show()
+```
+
+#### BIG TEXT
+
+![Big Text Notification](./assets/types/big-text.svg)
+
+For instances where you'd like to show a longer message you can use the `BigText` notification type. These kinds of messages are ideal for things such as email content, and news previews.
+
+```Kotlin
+Notify
+    .with(context)
+    .asBigText { // this: Payload.Content.TextList
+        // The title of the notification.
+        title = "Chocolate brownie sundae"
+        // The second line of the (collapsed) notification.
+        text = "Try our newest dessert option!"
+        // The second line of the expanded notification.
+        expandedText = "Try our newest dessert option!"
+        // Large string that is displayed under the line above.
+        bigText = "Our own Fabulous Godiva Chocolate Brownie, Vanilla " +
+                  "Ice Cream, Hot Fudge, Whipped Cream and Toasted " + 
+                  "Almonds.\n\n" +
+                  "Come try this delicious new dessert and get two for " +
+                  "the price of one!"
+    }
+    .show()
+```
+
+#### BIG PICTURE
+
+![Big Picture Notification](./assets/types/big-picture.svg)
+
+The big picture allows an application to notify the user in a manner similar to the [screenshot saved](https://www.androidexplained.com/wp-content/uploads/2017/10/Pixel-2-Screenshot-Notification.png) notification which shows a preview of the screenshot within the main content of the notification.
+
+```Kotlin
+Notify
+    .with(context)
+    .asBigPicture {
+        // The title of the notification.
+        title = "Chocolate brownie sundae"
+        // The second line of the (collapsed) notification.
+        text = "Get a look at this amazing dessert!"
+        // The second line of the expanded notification.
+        expandedText = "The delicious brownie sundae now available."
+        // A bitmap that is to be shown. The system will automatically resize
+        // the image.
+        image = BitmapFactory.decodeResource(context.resources,
+                                             R.drawable.chocolate_brownie_sundae)
+    }
+    .show()
+```
+
+#### MESSAGE NOTIFICATION
+
+![Messages notification](./assets/types/messages.svg)
+
+The message notification is useful when displaying conversations within an application. It can also be useful to set the `headerText` field of the `Header` block with the number of messages outside the scope (list.size - 6).
+
+```Kotlin
+Notify
+    .with(context)
+    .asMessage {
+        userDisplayName = "Karn"
+        conversationTitle = "Sundae chat"
+        messages = Arrays.asList(
+                       NotificationCompat.MessagingStyle.Message(
+                           "Are you guys ready to try the Strawberry sundae?",
+                           System.currentTimeMillis() - (6 * 60 * 1000), // 6 Mins ago
+                           "Karn"),
+                       NotificationCompat.MessagingStyle.Message(
+                           "Yeah! I've heard great things about this place.",
+                           System.currentTimeMillis() - (5 * 60 * 1000), // 5 Mins ago
+                           "Nitish"),
+                       NotificationCompat.MessagingStyle.Message("What time are you getting there Karn?",
+                           System.currentTimeMillis() - (1 * 60 * 1000), // 1 Mins ago
+                           "Moez")
+                    )
+    }
+    .show()
+```

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,5 @@
-#Wed Apr 25 23:19:53 EDT 2018
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-4.6-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-4.5-all.zip

library/src/main/java/io/karn/notify/Notify.kt

@@ -4,7 +4,9 @@ import android.app.NotificationManager
 import android.content.Context
 import android.support.v4.app.NotificationCompat
 import io.karn.notify.entities.NotifyConfig
-import io.karn.notify.entities.RawNotification
+import io.karn.notify.internal.RawNotification
+import io.karn.notify.internal.NotificationChannelInterop
+import io.karn.notify.internal.NotificationInterop
 
 /**
  * Simplified Notification delivery for Android.
@@ -15,70 +17,96 @@ class Notify internal constructor(internal var context: Context) {
         /**
          * The default CHANNEL_ID for a notification on Android O.
          */
-        const val DEFAULT_CHANNEL_KEY = "application_notification"
+        const val CHANNEL_DEFAULT_KEY = "application_notification"
         /**
          * The default CHANNEL_NAME for a notification on Android O.
          */
-        const val DEFAULT_CHANNEL_NAME = "Application notifications."
+        const val CHANNEL_DEFAULT_NAME = "Application notifications."
         /**
          * The default CHANNEL_DESCRIPTION for a notification on Android O.
          */
-        const val DEFAULT_CHANNEL_DESCRIPTION = "General application notifications."
+        const val CHANNEL_DEFAULT_DESCRIPTION = "General application notifications."
+        /**
+         * Lowest priority for a notification. These notifications might not be shown to the user except under special
+         * circumstances, such as detailed notification logs.
+         */
+        const val IMPORTANCE_MIN = NotificationCompat.PRIORITY_MIN
+        /**
+         * Lower priority for notifications that are deemed less important. The UI may choose to show these items
+         * smaller, or at a different position in the list, compared to notifications with normal importance.
+         */
+        const val IMPORTANCE_LOW = NotificationCompat.PRIORITY_LOW
+        /**
+         * Default priority for notifications. If your application does not prioritize its own notifications, use this
+         * value for all notifications.
+         */
+        const val IMPORTANCE_NORMAL = NotificationCompat.PRIORITY_DEFAULT
+        /**
+         * Higher priority for notifications, for more important notifications or alerts. The UI may choose to show
+         * these items larger, or at a different position in notification lists, compared with your app's notifications
+         * of normal importance.
+         */
+        const val IMPORTANCE_HIGH = NotificationCompat.PRIORITY_HIGH
+        /**
+         * Highest priority for notifications, use for notifications that require the user's prompt attention or input.
+         */
+        const val IMPORTANCE_MAX = NotificationCompat.PRIORITY_MAX
+
+        /**
+         * The flag to disable notification lights.
+         */
+        const val NO_LIGHTS = 0
 
-        // This is the initial configuration of the Notify Creator.
+        // This is the initial configuration of the Notify NotifyCreator.
         internal var defaultConfig = NotifyConfig()
 
         /**
          * Modify the default configuration.
          *
          * Takes a receiver with the NotifyConfig immutable object which has mutable fields.
          */
-        fun defaultConfig(block: (NotifyConfig) -> Unit) {
-            block(defaultConfig)
+        fun defaultConfig(init: NotifyConfig.() -> Unit) {
+            defaultConfig.init()
         }
 
         /**
-         * A new {@see Notify} and {@see Creator} instance.
+         * A new {@see Notify} and {@see NotifyCreator} instance.
          *
-         * This object is automatically initialized with the singleton default configuration which
-         * can be modified using {@see Notify#defaultConfig((NotifyConfig) -> Unit)}.
+         * This object is automatically initialized with the singleton default configuration which can be modified using
+         * {@see Notify#defaultConfig((NotifyConfig) -> Unit)}.
          */
-        fun with(context: Context): Creator {
-            return Creator(Notify(context), defaultConfig)
+        fun with(context: Context): NotifyCreator {
+            return NotifyCreator(Notify(context), defaultConfig)
         }
     }
 
     init {
         this.context = context.applicationContext
 
         // Initialize notification manager instance.
-        if (Companion.defaultConfig.notificationManager == null) {
-            Companion.defaultConfig.notificationManager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+        if (defaultConfig.notificationManager == null) {
+            defaultConfig.notificationManager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
         }
 
-        NotifyChannel.registerChannel(
-                Companion.defaultConfig.notificationManager!!,
-                defaultConfig.defaultChannelKey,
-                defaultConfig.defaultChannelName,
-                defaultConfig.defaultChannelDescription)
+        NotificationChannelInterop.with(defaultConfig.defaultAlerting)
     }
 
     /**
-     * Return the standard {@see NotificationCompat.Builder} after applying fluent API
-     * transformations (if any) from the {@see Creator} builder object.
+     * Return the standard {@see NotificationCompat.Builder} after applying fluent API transformations (if any) from the
+     * {@see NotifyCreator} builder object.
      */
     internal fun asBuilder(payload: RawNotification): NotificationCompat.Builder {
         return NotificationInterop.buildNotification(this, payload)
     }
 
     /**
-     * Delegate a {@see Notification.Builder} object to the Notify NotificationInterop class which
-     * builds and displays the notification.
+     * Delegate a {@see Notification.Builder} object to the Notify NotificationInterop class which builds and displays
+     * the notification.
      *
      * This is a terminal operation.
      *
-     * @return An integer corresponding to the ID of the system notification. Any updates should use
-     * this returned integer to make updates or to cancel the notification.
+     * @return An integer corresponding to the ID of the system notification. Any updates should use this returned
+     * integer to make updates or to cancel the notification.
      */
     internal fun show(builder: NotificationCompat.Builder): Int {
         return NotificationInterop.showNotification(Notify.defaultConfig.notificationManager!!, builder)