Notification endpoints (#3096)

* Initial notification schema

* Add: notification event and settings schema

* Add: NotificationController

* Update bundled spec

* Fix: `operationId` typos

* Fix: library response to be arroy of objects

* Fix: notification ID is not uuid

* Add: `nullable` notification creation parameters

* Nullable libraryId schema

* Remove: `id` from Notification requestBody

* Fix: `allOf` for `libraryItemSequence`

* Fix: required `id` in wrong body

* Fix: libraryItem typos

* Update: bundled spec

docs/objects/Library.yaml

@@ -10,6 +10,12 @@ components:
       description: The ID of the library.
       format: uuid
       example: 'e4bb1afb-4a4f-4dd6-8be0-e615d233185b'
+    libraryIdNullable:
+      type: string
+      description: The ID of the library. Applies to all libraries if `null`.
+      format: uuid
+      nullable: true
+      example: 'e4bb1afb-4a4f-4dd6-8be0-e615d233185b'
     libraryName:
       description: The name of the library.
       type: string

docs/objects/LibraryItem.yaml

@@ -69,4 +69,7 @@ components:
       description: A single item on the server, like a book or podcast. Includes series sequence information.
       allOf:
         - $ref: '#/components/schemas/libraryItemBase'
-        - $ref: './entities/Series.yaml#/components/schemas/sequence'
+        - type: object
+          properties:
+            sequence:
+              $ref: './entities/Series.yaml#/components/schemas/sequence'

docs/objects/Notification.yaml

@@ -0,0 +1,142 @@
+components:
+  schemas:
+    notificationId:
+      type: string
+      description: The ID of the notification.
+      example: notification-settings
+      # This is using a value of `notification-settings`, not a UUID. Need to investigate
+      #format: uuid
+      #example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
+    appriseApiUrl:
+      type: string
+      nullable: true
+      description: The full URL where the Apprise API to use is located.
+    maxFailedAttempts:
+      type: integer
+      minimum: 0
+      default: 5
+      description: The maximum number of times a notification fails before being disabled.
+    maxNotificationQueue:
+      type: integer
+      description: The maximum number of notifications in the notification queue before events are ignored.
+    notificationEventName:
+      type: string
+      description: The name of the event the notification will fire on.
+      enum: ['onPodcastEpisodeDownloaded', 'onTest']
+    urls:
+      type: array
+      items:
+        type: string
+      description: The Apprise URLs to use for the notification.
+      example: http://192.168.0.3:8000/notify/my-cool-notification
+    titleTemplate:
+      type: string
+      description: The template for the notification title.
+      example: 'New {{podcastTitle}} Episode!'
+    bodyTemplate:
+      type: string
+      description: The template for the notification body.
+      example: '{{episodeTitle}} has been added to {{libraryName}} library.'
+    enabled:
+      type: boolean
+      default: false
+      description: Whether the notification is enabled.
+    notificationType:
+      type: string
+      enum: ['info', 'success', 'warning', 'failure']
+      nullable: true
+      default: 'info'
+      description: The notification's type.
+    Notification:
+      type: object
+      properties:
+        id:
+          $ref: '#/components/schemas/notificationId'
+        libraryId:
+          $ref: './Library.yaml#/components/schemas/libraryIdNullable'
+        eventName:
+          $ref: '#/components/schemas/notificationEventName'
+        urls:
+          $ref: '#/components/schemas/urls'
+        titleTemplate:
+          $ref: '#/components/schemas/titleTemplate'
+        bodyTemplate:
+          $ref: '#/components/schemas/bodyTemplate'
+        enabled:
+          $ref: '#/components/schemas/enabled'
+        type:
+          $ref: '#/components/schemas/notificationType'
+        lastFiredAt:
+          type: integer
+          nullable: true
+          description: The time (in ms since POSIX epoch) when the notification was last fired. Will be null if the notification has not fired.
+        lastAttemptFailed:
+          type: boolean
+          description: Whether the last notification attempt failed.
+        numConsecutiveFailedAttempts:
+          type: integer
+          description: The number of consecutive times the notification has failed.
+          default: 0
+        numTimesFired:
+          type: integer
+          description: The number of times the notification has fired.
+          default: 0
+        createdAt:
+          $ref: '../schemas.yaml#/components/schemas/createdAt'
+    NotificationEvent:
+      type: object
+      properties:
+        name:
+          type: string
+          description: The name of the notification event. The names and allowable values are defined at https://github.com/advplyr/audiobookshelf/blob/master/server/utils/notifications.js
+        requiresLibrary:
+          type: boolean
+          description: Whether the notification event depends on a library existing.
+        libraryMediaType:
+          type: string
+          description: The type of media of the library the notification depends on existing. Will not exist if requiresLibrary is false.
+          nullable: true
+        description:
+          type: string
+          description: The description of the notification event.
+        variables:
+          type: array
+          items:
+            type: string
+          description: The variables of the notification event that can be used in the notification templates.
+        defaults:
+          type: object
+          properties:
+            title:
+              type: string
+              description: The default title template for notifications using the notification event.
+            body:
+              type: string
+              description: The default body template for notifications using the notification event.
+        testData:
+          type: object
+          description: The keys of the testData object will match the list of variables. The values will be the data used when sending a test notification.
+          additionalProperties:
+            type: string
+    NotificationSettings:
+      type: object
+      properties:
+        id:
+          $ref: '#/components/schemas/notificationId'
+        appriseType:
+          type: string
+          description: The type of Apprise that will be used. At the moment, only api is available.
+        appriseApiUrl:
+          $ref: '#/components/schemas/appriseApiUrl'
+        notifications:
+          type: array
+          items:
+            $ref: '#/components/schemas/Notification'
+          description: The set notifications.
+        maxFailedAttempts:
+          $ref: '#/components/schemas/maxFailedAttempts'
+        maxNotificationQueue:
+          $ref: '#/components/schemas/maxNotificationQueue'
+        notificationDelay:
+          type: integer
+          description: The time (in ms) between notification pushes.