From 7274b87aca6b359d626638a92a0931e5b9dca104 Mon Sep 17 00:00:00 2001
From: Vito0912 <86927734+Vito0912@users.noreply.github.com>
Date: Thu, 1 Aug 2024 19:42:24 +0200
Subject: [PATCH] Added some new endpoints

---
 docs/controllers/MeController.yaml      | 130 ++++++++++++++++++
 docs/controllers/SessionController.yaml | 170 ++++++++++++++++++++++++
 docs/openapi.json                       | Bin 327344 -> 353792 bytes
 docs/root.yaml                          |  18 +++
 4 files changed, 318 insertions(+)

diff --git a/docs/controllers/MeController.yaml b/docs/controllers/MeController.yaml
index e8165b322..b461ea886 100644
--- 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
index 70cab2843..3a1f17057 100644
--- 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
index c5edd27062000ca9547876cbe9f45d5a7972a069..97ce3d814827371d8afee1ed3080965b5fba1ec1 100644
GIT binary patch
delta 2994
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

delta 64
zcmZoTBf8<Q@P<olllL%*HDBUrzr?|~{SpV$zp&|VQdzm$MUF55G4pnjBP>-dlON>C
UO+FK(HT}R*Ccf<gUaTLa0hFg3DF6Tf

diff --git a/docs/root.yaml b/docs/root.yaml
index 63462a22c..b93d88a68 100644
--- 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