Add: NotificationController

docs/controllers/NotificationController.yaml

@@ -0,0 +1,227 @@
+components:
+  responses:
+    notification200:
+      description: Notification endpoint success.
+      content:
+        text/html:
+          schema:
+            type: string
+            example: OK
+    notification404:
+      description: An admin user is required or notification with the given ID not found.
+      content:
+        text/html:
+          schema:
+            type: string
+            example: Series not found.
+paths:
+  /api/notifications:
+    get:
+      operationId: getNotifications
+      description: Get all Apprise notification events and notification settings for server.
+      tags:
+        - Notification
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: object
+                    properties:
+                      events:
+                        type: array
+                        items:
+                          $ref: '../objects/Notification.yaml#/components/schemas/NotificationEvent'
+                  settings:
+                    $ref: '../objects/Notification.yaml#/components/schemas/NotificationSettings'
+        '404':
+          $ref: '#/components/responses/notification404'
+    patch:
+      operation: updateNotificationSettings
+      description: Update Notification settings.
+      tags:
+        - Notification
+      requestBody:
+        description: The Apprise Notification settings
+        content:
+          application/json:
+            schema:
+              properties:
+                appriseApiUrl:
+                  $ref: '../objects/Notification.yaml#/components/schemas/appriseApiUrl'
+                maxFailedAttempts:
+                  $ref: '../objects/Notification.yaml#/components/schemas/maxFailedAttempts'
+                maxNotificationQueue:
+                  $ref: '../objects/Notification.yaml#/components/schemas/maxNotificationQueue'
+      responses:
+        '200':
+          $ref: '#/components/responses/notification200'
+        '404':
+          $ref: '#/components/responses/notification404'
+    post:
+      operation: createNotification
+      description: Update Notification settings.
+      tags:
+        - Notification
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                libraryId:
+                  $ref: '../objects/Library.yaml#/components/schemas/libraryId'
+                eventName:
+                  $ref: '../objects/Notification.yaml#/components/schemas/notificationEventName'
+                urls:
+                  $ref: '../objects/Notification.yaml#/components/schemas/urls'
+                titleTemplate:
+                  $ref: '../objects/Notification.yaml#/components/schemas/titleTemplate'
+                bodyTemplate:
+                  $ref: '../objects/Notification.yaml#/components/schemas/bodyTemplate'
+                enabled:
+                  $ref: '../objects/Notification.yaml#/components/schemas/enabled'
+                type:
+                  $ref: '../objects/Notification.yaml#/components/schemas/notificationType'
+              required:
+                - eventName
+                - urls
+                - titleTemplate
+                - bodyTemplate
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  settings:
+                    $ref: '../objects/Notification.yaml#/components/schemas/NotificationSettings'
+        '404':
+          $ref: '#/components/responses/notification404'
+  /api/notificationdata:
+    get:
+      operationId: getNotificationEventData
+      description: Get all Apprise notification event data for the server.
+      tags:
+        - Notification
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  events:
+                    type: array
+                    items:
+                      $ref: '../objects/Notification.yaml#/components/schemas/NotificationEvent'
+        '404':
+          $ref: '#/components/responses/notification404'
+  /api/notifications/test:
+    get:
+      operationId: sendDefaultTestNotification
+      description: Send a test notification.
+      tags:
+        - Notification
+      parameters:
+        - in: query
+          name: fail
+          description: Whether to intentionally cause the notification to fail. `0` for false, `1` for true.
+          schema:
+            type: integer
+      responses:
+        '200':
+          $ref: '#/components/responses/notification200'
+        '404':
+          $ref: '#/components/responses/notification404'
+  /api/notifications/{id}:
+    parameters:
+      - name: id
+        in: path
+        description: The ID of the notification.
+        required: true
+        schema:
+          $ref: '../objects/Notification.yaml#/components/schemas/notificationId'
+    delete:
+      operationId: deleteNotification
+      description: Delete the notification by ID and return the notification settings.
+      tags:
+        - Notification
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  settings:
+                    $ref: '../objects/Notification.yaml#/components/schemas/NotificationSettings'
+        '404':
+          $ref: '#/components/responses/notification404'
+    patch:
+      operation: createNotification
+      description: Update Notification settings.
+      tags:
+        - Notification
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                id:
+                  $ref: '../objects/Notification.yaml#/components/schemas/notificationId'
+                libraryId:
+                  $ref: '../objects/Library.yaml#/components/schemas/libraryId'
+                eventName:
+                  $ref: '../objects/Notification.yaml#/components/schemas/notificationEventName'
+                urls:
+                  $ref: '../objects/Notification.yaml#/components/schemas/urls'
+                titleTemplate:
+                  $ref: '../objects/Notification.yaml#/components/schemas/titleTemplate'
+                bodyTemplate:
+                  $ref: '../objects/Notification.yaml#/components/schemas/bodyTemplate'
+                enabled:
+                  $ref: '../objects/Notification.yaml#/components/schemas/enabled'
+                type:
+                  $ref: '../objects/Notification.yaml#/components/schemas/notificationType'
+              required:
+                - id
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  settings:
+                    $ref: '../objects/Notification.yaml#/components/schemas/NotificationSettings'
+        '404':
+          $ref: '#/components/responses/notification404'
+  /api/notifications/{id}/test:
+    parameters:
+      - name: id
+        in: path
+        description: The ID of the notification.
+        required: true
+        schema:
+          $ref: '../objects/Notification.yaml#/components/schemas/notificationId'
+    get:
+      operationId: sendTestNotification
+      description: Send a test to the given notification.
+      tags:
+        - Notification
+      responses:
+        '200':
+          $ref: '#/components/responses/notification200'
+        '404':
+          $ref: '#/components/responses/notification404'

docs/objects/Notification.yaml

@@ -5,6 +5,45 @@ components:
       description: The ID of the notification.
       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']
+      default: 'info'
+      description: The notification's type.
     Notification:
       type: object
       properties:
@@ -13,31 +52,17 @@ components:
         libraryId:
           $ref: './Library.yaml#/components/schemas/libraryId'
         eventName:
-          type: string
+          $ref: '#/components/schemas/notificationEventName'
-          description: The name of the event the notification will fire on.
-          enum: ['onPodcastEpisodeDownloaded', 'onTest']
         urls:
-          type: array
+          $ref: '#/components/schemas/urls'
-          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
+          $ref: '#/components/schemas/titleTemplate'
-          description: The template for the notification title.
-          example: 'New {{podcastTitle}} Episode!'
         bodyTemplate:
-          type: string
+          $ref: '#/components/schemas/bodyTemplate'
-          description: The template for the notification body.
-          example: '{{episodeTitle}} has been added to {{libraryName}} library.'
         enabled:
-          type: boolean
+          $ref: '#/components/schemas/enabled'
-          description: Whether the notification is enabled.
         type:
-          type: string
+          $ref: '#/components/schemas/notificationType'
-          enum: ['info', 'success', 'warning', 'failure']
-          default: 'info'
-          description: The notification's type.
         lastFiredAt:
           type: integer
           nullable: true
@@ -99,20 +124,16 @@ components:
           type: string
           description: The type of Apprise that will be used. At the moment, only api is available.
         appriseApiUrl:
-          type: string
+          $ref: '#/components/schemas/appriseApiUrl'
-          nullable: true
-          description: The full URL where the Apprise API to use is located.
         notifications:
           type: array
           items:
             $ref: '#/components/schemas/Notification'
           description: The set notifications.
         maxFailedAttempts:
-          type: integer
+          $ref: '#/components/schemas/maxFailedAttempts'
-          description: The maximum number of times a notification fails before being disabled.
         maxNotificationQueue:
-          type: integer
+          $ref: '#/components/schemas/maxNotificationQueue'
-          description: The maximum number of notifications in the notification queue before events are ignored.
         notificationDelay:
           type: integer
           description: The time (in ms) between notification pushes.