Added some new endpoints

Vito0912 · Aug 1, 2024 · 7274b87 · 7274b87
1 parent 811893f
commit 7274b87
Show file tree

Hide file tree

Showing 4 changed files with 318 additions and 0 deletions.
diff --git a/docs/controllers/MeController.yaml b/docs/controllers/MeController.yaml
@@ -1,3 +1,9 @@
+components:
+  schemas:
+    totalTime:
+      description: The total time listened in seconds.
+      type: integer
+      example: 123456
 paths:
   /api/me:
     get:
@@ -75,3 +81,127 @@ paths:
                   schema:
                       type: string
                       example: Not Found
+  /api/me/listening-sessions:
+    get:
+      operationId: getListeningSessions
+      summary: Get all listening sessions for the current user.
+      description: Get all listening sessions for the current user.
+      tags:
+        - Me
+      parameters:
+        - name: itemsPerPage
+          in: query
+          description: The number of items per page.
+          required: true
+          schema:
+              $ref: '../schemas.yaml#/components/schemas/limit'
+        - name: page
+          in: query
+          description: The page number (zero indexed) to return.
+          required: true
+          schema:
+              $ref: '../schemas.yaml#/components/schemas/page'
+      responses:
+        '200':
+            description: OK
+            content:
+                application/json:
+                  schema:
+                      type: object
+                      properties:
+                          total:
+                              $ref: '../schemas.yaml#/components/schemas/total'
+                          numPages:
+                              description: The number of pages.
+                              type: integer
+                          itemsPerPage:
+                            $ref: '../schemas.yaml#/components/schemas/limit'
+                          sessions:
+                              type: array
+                              items:
+                                  $ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSession'
+  /api/me/items-in-progress:
+    get:
+      operationId: getItemsInProgress
+      summary: Get all items in progress for the current user.
+      description: Get all items in progress for the current user.
+      tags:
+        - Me
+      parameters:
+        - name: limit
+          in: query
+          description: The number of items to return.
+          required: false
+          schema:
+              $ref: '../schemas.yaml#/components/schemas/limit'
+      responses:
+        '200':
+            description: OK
+            content:
+                application/json:
+                  schema:
+                      type: object
+                      properties:
+                          total:
+                              $ref: '../schemas.yaml#/components/schemas/total'
+                          numPages:
+                              description: The number of pages.
+                              type: integer
+                          itemsPerPage:
+                            $ref: '../schemas.yaml#/components/schemas/limit'
+                          items:
+                              type: array
+                              items:
+                                  $ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItemMinified'
+  /api/me/listening-stats:
+    get:
+      operationId: getListeningStats
+      summary: Get listening stats for the current user.
+      description: Get listening stats for the current user.
+      tags:
+        - Me
+      responses:
+        '200':
+            description: OK
+            content:
+                application/json:
+                  schema:
+                      type: object
+                      properties:
+                          totalTime:
+                              $ref: '#/components/schemas/totalTime'
+                          items:
+                            type: object
+                            description: A list of library items the user has listened to, keyed by their item IDs.
+                            additionalProperties:
+                              type: object
+                              properties:
+                                id:
+                                  type: string
+                                  description: The ID of the library item.
+                                timeListening:
+                                  type: integer
+                                  description: The time (in seconds) the user listened to this library item.
+                                mediaMetadata:
+                                  oneOf:
+                                    - $ref: '../objects/metadata/BookMetadata.yaml#/components/schemas/bookMetadata'
+                                    - $ref: '../objects/metadata/PodcastMetadata.yaml#/components/schemas/PodcastMetadata'
+                          days:
+                            type: object
+                            description: A mapping of days to total listening times.
+                            additionalProperties:
+                              type: integer
+                              description: The total time (in seconds) listened to on that day.
+                          dayOfWeek:
+                            type: object
+                            description: A mapping of days of the week to total listening times.
+                            additionalProperties:
+                              type: integer
+                              description: The total time (in seconds) listened to on that day of the week.
+                          today:
+                            type: integer
+                            description: The time (in seconds) the user has listened to library items today.
+                          recentSessions:
+                            type: array
+                            items:
+                                $ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSession'
diff --git a/docs/controllers/SessionController.yaml b/docs/controllers/SessionController.yaml
@@ -53,3 +53,173 @@ paths:
                   schema:
                       type: string
                       example: Internal Server Error
+  /api/sessions/{id}:
+    delete:
+      operationId: deleteSession
+      summary: Delets a listening session.
+      description: Deletes a listening session.
+      tags:
+        - Session
+      parameters:
+        - name: id
+          in: path
+          description: The ID of the session.
+          required: true
+          schema:
+            $ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSessionId'
+      responses:
+        '200':
+            description: OK
+            content:
+                html/text:
+                  schema:
+                      type: string
+                      example: OK
+        '403':
+            description: A user with delete permissions is required to delete sessions.
+            content:
+                html/text:
+                  schema:
+                      type: string
+                      example: Forbidden
+        '404':
+            description: No listening session with the provided ID was found.
+            content:
+                html/text:
+                  schema:
+                      type: string
+                      example: Not Found
+  /api/session/{id}/close:
+    post:
+      operationId: closeSession
+      summary: Close a listening session.
+      description: Close a listening session.
+      tags:
+        - Session
+      parameters:
+        - name: id
+          in: path
+          description: The ID of the session.
+          required: true
+          schema:
+            $ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSessionId'
+        - name: currentTime
+          in: query
+          description: The current time of the session.
+          required: false
+          schema:
+            $ref: '../schemas.yaml#/components/schemas/durationSec'
+        - name: timeListened
+          in: query
+          description: The time listened to the session.
+          required: false
+          schema:
+            $ref: '../schemas.yaml#/components/schemas/durationSec'
+        - name: duration
+          in: query
+          description: The duration of the session.
+          required: false
+          schema:
+            $ref: '../schemas.yaml#/components/schemas/durationSec'
+      responses:
+        '200':
+            description: OK
+            content:
+                html/text:
+                  schema:
+                      type: string
+                      example: OK
+        '404':
+            description: No listening session with the provided ID is open, or the session belongs to another user.
+            content:
+                html/text:
+                  schema:
+                      type: string
+                      example: Not Found
+  /api/session/{id}:
+    get:
+        operationId: getSession
+        summary: Get a listening session.
+        description: Get a listening session.
+        tags:
+            - Session
+        parameters:
+            - name: id
+              in: path
+              description: The ID of the session.
+              required: true
+              schema:
+                $ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSessionId'
+        responses:
+            '200':
+                description: OK
+                content:
+                    application/json:
+                      schema:
+                        $ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSessionExpanded'
+            '404':
+                description: No listening session with the provided ID was found.
+                content:
+                    html/text:
+                      schema:
+                          type: string
+                          example: Not Found
+  /api/sessions:
+    get:
+        operationId: getSessions
+        summary: Get all listening sessions.
+        description: Get all listening sessions.
+        tags:
+            - Session
+        parameters:
+          - name: user
+            in: query
+            description: The ID of the user to filter listening sessions by.
+            required: false
+            schema:
+                $ref: '../objects/entities/User.yaml#/components/schemas/userId'
+          - name: itemsPerPage
+            in: query
+            description: The number of items to return.
+            required: false
+            schema:
+                $ref: '../schemas.yaml#/components/schemas/limit'
+          - name: page
+            in: query
+            description: The page number (zero indexed) to return.
+            required: false
+            schema:
+                $ref: '../schemas.yaml#/components/schemas/page'
+        responses:
+            '200':
+                description: OK
+                content:
+                    application/json:
+                      schema:
+                        type: object
+                        properties:
+                          results:
+                            type: array
+                            items:
+                              $ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItemBase'
+                          total:
+                            $ref: '../schemas.yaml#/components/schemas/total'
+                          itemsPerPage:
+                            $ref: '../schemas.yaml#/components/schemas/limit'
+                          numPages:
+                            description: The number of pages.
+                            type: integer
+                            example: 10
+                          userFilter:
+                            description: If provided, the `user` parameter.
+                          sessions:
+                            type: array
+                            items:
+                              $ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSession'
+            '404':
+                description: No listening sessions were found.
+                content:
+                    html/text:
+                      schema:
+                          type: string
+                          example: Not Found
diff --git a/docs/openapi.json b/docs/openapi.json
diff --git a/docs/root.yaml b/docs/root.yaml
@@ -93,6 +93,18 @@ paths:
     $ref: './controllers/MeController.yaml#/paths/~1api~1me~1progress~1{mediaId}'
   /api/session/{id}/sync:
     $ref: './controllers/SessionController.yaml#/paths/~1api~1session~1{id}~1sync'
+  /api/sessions/{id}:
+    $ref: './controllers/SessionController.yaml#/paths/~1api~1sessions~1{id}'
+  /api/session/{id}/close:
+    $ref: './controllers/SessionController.yaml#/paths/~1api~1session~1{id}~1close'
+  /api/session/{id}:
+    $ref: './controllers/SessionController.yaml#/paths/~1api~1session~1{id}'
+  /api/sessions:
+    $ref: './controllers/SessionController.yaml#/paths/~1api~1sessions'
+  /api/me/listening-sessions:
+    $ref: './controllers/MeController.yaml#/paths/~1api~1me~1listening-sessions'
+  /api/me/listening-stats:
+    $ref: './controllers/MeController.yaml#/paths/~1api~1me~1listening-stats'
 tags:
   - name: Authors
     description: Author endpoints
@@ -106,3 +118,9 @@ tags:
     description: Notifications endpoints
   - name: Podcasts
     description: Podcast endpoints
+  - name: Auth
+    description: Authentication endpoints
+  - name: Me
+    description: User endpoints
+  - name: Session
+    description: Session endpoints