openapi.yaml

openapi: 3.0.3
info:
  title: gdl-api
  description: gdl-api express server
  version: 'v0.4'
servers:
  - url: https://gdl.mcalec.dev/api
    description: production server
  - url: http://localhost:3030/api
    description: local server
tags:
  - name: API
    description: General API information
  - name: Authentication
    description: User authentication and OAuth
  - name: Files
    description: File and directory operations
  - name: Downloads
    description: File downloads
  - name: Uploads
    description: File uploads
  - name: Random
    description: Random file retrieval
  - name: Search
    description: File and directory search
  - name: Statistics
    description: API and system statistics
  - name: Health
    description: Health check endpoints
  - name: User
    description: User profile and settings
  - name: Admin
    description: Administrative operations
  - name: Pools
    description: File pool management
paths:
  /:
    get:
      tags:
        - API
      summary: Get API information and available endpoints
      description: Retrieve general API information, version, and list of available endpoints
      responses:
        '200':
          description: API information with available endpoint URLs
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  version:
                    type: string
                  description:
                    type: string
                  author:
                    type: string
                  keywords:
                    type: array
                    items:
                      type: string
                  license:
                    type: string
                  host:
                    type: string
                  basePath:
                    type: string
                  urls:
                    type: object
                    properties:
                      admin:
                        type: string
                      auth:
                        type: string
                      user:
                        type: string
                      files:
                        type: string
                      health:
                        type: string
                      random:
                        type: string
                      search:
                        type: string
                      stats:
                        type: string
                      upload:
                        type: string
                      pool:
                        type: string
  /auth/:
    get:
      tags:
        - Authentication
      summary: Get auth API information
      description: Get available authentication endpoints
      responses:
        '200':
          description: Auth endpoints
          content:
            application/json:
              schema:
                type: object
                properties:
                  urls:
                    type: object
                    properties:
                      check:
                        type: string
                      login:
                        type: string
                      logout:
                        type: string
                      provider:
                        type: string
                      register:
                        type: string
  /auth/check/:
    get:
      tags:
        - Authentication
      summary: Check user authentication status
      description: Check if the current user is authenticated and retrieve their authentication details
      responses:
        '200':
          description: Authentication status and user information
          content:
            application/json:
              schema:
                type: object
                properties:
                  authenticated:
                    type: boolean
                  user:
                    type: object
                  roles:
                    type: array
                    items:
                      type: string
                  oauth:
                    type: object
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /auth/login/:
    post:
      tags:
        - Authentication
      summary: User login with username/email and password
      description: Authenticate a user with their credentials (username or email and password)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: Username or email of the user
                email:
                  type: string
                  description: Email address of the user (alternative to username)
                password:
                  type: string
                  description: User password
              required:
                - password
      responses:
        '201':
          description: User successfully logged in
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  user:
                    type: object
        '400':
          description: Missing credentials, user not found, or invalid password
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: User already logged in
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /auth/logout/:
    post:
      tags:
        - Authentication
      summary: User logout
      description: Log out the authenticated user and destroy their session
      responses:
        '201':
          description: User successfully logged out
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /auth/register/:
    post:
      tags:
        - Authentication
      summary: User registration
      description: Register a new user with username, email, and password
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: Unique username for the user
                email:
                  type: string
                  format: email
                  description: Email address of the user
                password:
                  type: string
                  description: Password for the user account
              required:
                - username
                - password
      responses:
        '201':
          description: User successfully registered and logged in
        '400':
          description: Missing required fields or invalid email format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Username or email already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /auth/provider/:
    get:
      tags:
        - Authentication
      summary: Get OAuth provider endpoints
      description: Get available OAuth provider endpoints for callback, login, link, and unlink operations
      responses:
        '200':
          description: OAuth provider URLs
          content:
            application/json:
              schema:
                type: object
                properties:
                  urls:
                    type: object
                    properties:
                      callback:
                        type: string
                      login:
                        type: string
                      link:
                        type: string
                      unlink:
                        type: string
  /auth/provider/login/{provider}:
    get:
      tags:
        - Authentication
      summary: Initiate OAuth login
      description: Start OAuth authentication flow for the specified provider
      parameters:
        - in: path
          name: provider
          required: true
          schema:
            type: string
            enum: [github, discord]
          description: OAuth provider name
      responses:
        '302':
          description: Redirect to provider authentication
        '400':
          description: Invalid provider
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /auth/provider/callback/{provider}:
    get:
      tags:
        - Authentication
      summary: OAuth callback endpoint
      description: Handle OAuth provider callback after successful authentication
      parameters:
        - in: path
          name: provider
          required: true
          schema:
            type: string
            enum: [github, discord]
          description: OAuth provider name
        - in: query
          name: code
          required: true
          schema:
            type: string
          description: Authorization code from provider
      responses:
        '302':
          description: Redirect to dashboard on success
  /auth/provider/link/{provider}:
    get:
      tags:
        - Authentication
      summary: Link OAuth account to existing user
      description: Link an OAuth provider account to the currently authenticated user
      parameters:
        - in: path
          name: provider
          required: true
          schema:
            type: string
            enum: [github, discord]
          description: OAuth provider name
      responses:
        '302':
          description: Redirect to provider authentication
        '400':
          description: Invalid provider or provider already linked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /auth/provider/unlink/{provider}:
    get:
      tags:
        - Authentication
      summary: Unlink OAuth account from user
      description: Remove OAuth provider account from the currently authenticated user
      parameters:
        - in: path
          name: provider
          required: true
          schema:
            type: string
            enum: [github, discord]
          description: OAuth provider name
      responses:
        '200':
          description: Provider unlinked successfully
        '400':
          description: Invalid provider or cannot unlink (no other auth method)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /files/:
    get:
      tags:
        - Files
      summary: Get all files and directories from the root
      description: List all files and directories from the BASE_DIR with optional sorting and pagination
      parameters:
        - in: query
          name: sort
          schema:
            type: string
            enum: [name, size, date, type]
          description: Field to sort by
        - in: query
          name: direction
          schema:
            type: string
            enum: [asc, desc]
          description: Sort direction
        - in: query
          name: limit
          schema:
            type: integer
          description: Maximum number of results (up to PAGINATION_LIMIT)
        - in: query
          name: page
          schema:
            type: integer
          description: Page number for pagination
        - in: query
          name: meta
          schema:
            type: boolean
          description: Include extended file metadata (uuid, hash, sidecar)
      responses:
        '200':
          description: List of files and directories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/File'
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /files/{collection}/:
    get:
      tags:
        - Files
      summary: Get files from a specific collection
      description: List files and subdirectories within a specific collection
      parameters:
        - in: path
          name: collection
          required: true
          schema:
            type: string
          description: Collection name
        - in: query
          name: sort
          schema:
            type: string
            enum: [name, size, date, type]
          description: Field to sort by
        - in: query
          name: direction
          schema:
            type: string
            enum: [asc, desc]
          description: Sort direction
      responses:
        '200':
          description: List of files in collection
        '400':
          description: Invalid path parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /files/{collection}/{author}/:
    get:
      tags:
        - Files
      summary: Get files from a specific author within a collection
      description: List files from a specific author directory within a collection
      parameters:
        - in: path
          name: collection
          required: true
          schema:
            type: string
          description: Collection name
        - in: path
          name: author
          required: true
          schema:
            type: string
          description: Author/subdirectory name
      responses:
        '200':
          description: List of files from author directory
        '404':
          description: Path not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /download/:
    get:
      tags:
        - Downloads
      summary: Download a file using its UUID
      description: Downloads a file from the server using the provided UUID. Supports both GET and POST methods.
      parameters:
        - in: query
          name: uuid
          required: true
          schema:
            type: string
          description: The UUID of the file to download
      responses:
        '200':
          description: File content as binary data
        '400':
          description: Missing or invalid uuid parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: File not found or not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
        - Downloads
      summary: Download a file using its UUID (POST method)
      description: Downloads a file from the server using the provided UUID via POST body.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                uuid:
                  type: string
                  description: The UUID of the file to download
              required:
                - uuid
      responses:
        '200':
          description: File content as binary data
        '400':
          description: Missing or invalid uuid parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: File not found or not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /upload/:
    post:
      tags:
        - Uploads
      summary: Upload a file to the server
      description: Upload a single file to GridFS storage with size limits
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload
              required:
                - file
      responses:
        '201':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  fileId:
                    type: string
                    description: The GridFS file ID
                  filename:
                    type: string
                  size:
                    type: number
                  uploadDate:
                    type: string
                    format: date-time
        '400':
          description: No file provided or file too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: File upload failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /uuid/{uuid}/{type}:
    get:
      tags:
        - Files
      summary: Retrieve file or directory information by UUID
      description: Retrieve detailed information about a file or directory using its UUID.
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
          description: The UUID of the file or directory to retrieve
        - in: path
          name: type
          required: true
          schema:
            type: string
            enum: [file, directory]
          description: The type of the entry to retrieve (file or directory)
      responses:
        '200':
          description: File or directory information retrieved successfully
        '400':
          description: Invalid UUID or type parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: File or directory not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /random:
    get:
      tags:
        - Random
      summary: Retrieve a random file
      description: Retrieve a random file from the database with metadata
      responses:
        '200':
          description: Random file metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  file:
                    type: string
                  path:
                    type: string
                  collection:
                    type: string
                  author:
                    type: string
                  size:
                    type: number
                  url:
                    type: string
                  created:
                    type: string
                    format: date-time
                  modified:
                    type: string
                    format: date-time
                  type:
                    type: string
                  hash:
                    type: string
                  uuid:
                    type: string
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No file found in database
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /random/:
    get:
      tags:
        - Random
      summary: Retrieve a random file (with trailing slash)
      description: Retrieve a random file from the database with metadata
      responses:
        '200':
          description: Random file metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  file:
                    type: string
                  path:
                    type: string
                  collection:
                    type: string
                  author:
                    type: string
                  size:
                    type: number
                  url:
                    type: string
                  created:
                    type: string
                    format: date-time
                  modified:
                    type: string
                    format: date-time
                  type:
                    type: string
                  hash:
                    type: string
                  uuid:
                    type: string
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No file found in database
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /pool:
    get:
      tags:
        - Pools
      summary: List all file pools
      description: Retrieve a paginated list of all file pools for the authenticated user
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            default: 100
          description: Maximum number of pools to return
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: Page number for pagination
      responses:
        '200':
          description: List of pools with pagination info
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Total number of pools
                  page:
                    type: integer
                  limit:
                    type: integer
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Pool'
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
        - Pools
      summary: Create a new file pool
      description: Create a new pool to group files together with optional description and tags
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the pool (required)
                description:
                  type: string
                  description: Optional description of the pool
                tags:
                  type: array
                  items:
                    type: string
                  description: Optional array of tags
                files:
                  type: array
                  items:
                    type: string
                  description: Optional array of file UUIDs to include in the pool
              required:
                - name
      responses:
        '201':
          description: Pool created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pool'
        '400':
          description: Invalid pool name or request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /pool/{uuid}:
    get:
      tags:
        - Pools
      summary: Retrieve a specific pool
      description: Get detailed information about a specific pool by UUID
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
          description: Pool UUID
        - in: query
          name: includeFiles
          schema:
            type: boolean
            default: false
          description: Whether to include full file details in the response
      responses:
        '200':
          description: Pool information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pool'
        '400':
          description: Invalid UUID parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Pool not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - Pools
      summary: Update a file pool
      description: Update pool properties such as name, description, tags, or files
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
          description: Pool UUID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: New pool name
                description:
                  type: string
                  description: New pool description
                tags:
                  type: array
                  items:
                    type: string
                  description: Updated tags array
                files:
                  type: array
                  items:
                    type: string
                  description: Updated file UUIDs array
      responses:
        '200':
          description: Pool updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pool'
        '400':
          description: Invalid UUID or request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Pool not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - Pools
      summary: Delete a file pool
      description: Remove a pool and its associations (files are not deleted)
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
          description: Pool UUID
      responses:
        '204':
          description: Pool deleted successfully
        '400':
          description: Invalid UUID parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Pool not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /pool/{uuid}/files:
    get:
      tags:
        - Pools
      summary: Get files in a pool
      description: Retrieve all files that are members of a specific pool
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
          description: Pool UUID
      responses:
        '200':
          description: Array of files in the pool
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/File'
        '400':
          description: Invalid UUID parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Pool not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
        - Pools
      summary: Add files to a pool
      description: Add one or more files to an existing pool by their UUIDs
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
          description: Pool UUID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                files:
                  type: array
                  items:
                    type: string
                  description: Array of file UUIDs to add to the pool (required)
              required:
                - files
      responses:
        '200':
          description: Files added to pool successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  count:
                    type: integer
                    description: Total number of files in the pool after operation
        '400':
          description: Invalid UUID or empty files array
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Pool or files not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /search/:
    get:
      tags:
        - Search
      summary: Search for files and directories with relevancy ranking
      description: Search the database for files and directories matching the query string
      parameters:
        - in: query
          name: q
          required: true
          schema:
            type: string
          description: Search query string
        - in: query
          name: type
          required: false
          schema:
            type: string
            enum: [file, directory]
          description: Filter by type (file or directory)
      responses:
        '200':
          description: Search results with relevancy ranking
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: string
                  count:
                    type: integer
                  results:
                    type: array
                    items:
                      type: object
        '400':
          description: Empty search query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /stats/:
    get:
      tags:
        - Statistics
      summary: Retrieve API and file statistics
      description: Retrieve statistics about the API, collections, file storage, and file types
      responses:
        '200':
          description: API and collection statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    description: API statistics
                  collections:
                    type: object
                    description: Collection statistics including totals and file types
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /health/:
    get:
      tags:
        - Health
      summary: Health check endpoint
      description: Check the health status of the API
      responses:
        '204':
          description: API is healthy
        '500':
          description: API is unhealthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /user/:
    get:
      tags:
        - User
      summary: Get user API information
      description: Get current authenticated user information and available user endpoints
      responses:
        '200':
          description: User information and available endpoints
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    type: object
                  urls:
                    type: object
                    properties:
                      announcements:
                        type: string
                      dashboard:
                        type: string
  /user/color/:
    get:
      tags:
        - User
      summary: Get user color preference
      description: Retrieve the color preference for the authenticated user
      responses:
        '200':
          description: User color preference
          content:
            application/json:
              schema:
                type: object
                properties:
                  color:
                    type: string
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
        - User
      summary: Set user color preference
      description: Update the color preference for the authenticated user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                color:
                  type: string
                  description: The new color preference (e.g., hex code)
              required:
                - color
      responses:
        '200':
          description: User color preference updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  color:
                    type: string
        '400':
          description: Invalid color value provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /user/dashboard/:
    get:
      tags:
        - User
      summary: Retrieve user dashboard information
      description: Retrieve dashboard information for the authenticated user including profile and sessions
      responses:
        '200':
          description: User dashboard data
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  username:
                    type: string
                  email:
                    type: string
                  roles:
                    type: array
                    items:
                      type: string
                  uuid:
                    type: string
                  created:
                    type: string
                    format: date-time
                  modified:
                    type: string
                    format: date-time
                  oauth:
                    type: object
                  sessions:
                    type: array
                    items:
                      type: object
                      properties:
                        uuid:
                          type: string
                        modified:
                          type: string
                          format: date-time
                        ip:
                          type: string
                        useragent:
                          type: string
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /user/session/:
    get:
      tags:
        - User
      summary: Retrieve user sessions
      description: Get a list of all active sessions for the authenticated user
      responses:
        '200':
          description: List of user sessions
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    uuid:
                      type: string
                    modified:
                      type: string
                      format: date-time
                    ip:
                      type: string
                    useragent:
                      type: string
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /user/session/{uuid}:
    delete:
      tags:
        - User
      summary: Delete a specific user session
      description: Delete (logout) a specific session by UUID
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
          description: Session UUID to delete
      responses:
        '204':
          description: Session deleted successfully
        '400':
          description: Missing or invalid UUID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /user/announcements:
    get:
      tags:
        - User
      summary: Retrieve public announcements
      description: Get a list of announcements for all users, sorted by creation date
      responses:
        '200':
          description: List of announcements
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    _id:
                      type: string
                    title:
                      type: string
                    message:
                      type: string
                    severity:
                      type: string
                      enum: [info, warning, error]
                    author:
                      type: string
                    created:
                      type: string
                      format: date-time
                    modified:
                      type: string
                      format: date-time
                    uuid:
                      type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /admin/:
    get:
      tags:
        - Admin
      summary: Get admin dashboard statistics
      description: Retrieve comprehensive admin statistics including uptime, user counts, and storage usage
      responses:
        '200':
          description: Admin statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  stats:
                    type: object
                    properties:
                      uptime:
                        type: integer
                        description: Server uptime in milliseconds
                      totalUsers:
                        type: integer
                      loggedInUsers:
                        type: integer
                      topTags:
                        type: array
                        items: {}
                      storageUsage:
                        type: integer
                      flags:
                        type: integer
                  urls:
                    type: object
                    properties:
                      announcements:
                        type: string
        '401':
          description: User not authenticated or not an admin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /admin/users:
    get:
      tags:
        - Admin
      summary: List all users
      description: Get a list of all registered users (not yet implemented)
      responses:
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /admin/user/{id}:
    get:
      tags:
        - Admin
      summary: Get user information
      description: Retrieve detailed information about a specific user (not yet implemented)
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: User ID
      responses:
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - Admin
      summary: Update user information
      description: Modify user account details (not yet implemented)
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: User ID
      responses:
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /admin/user/{id}/action:
    post:
      tags:
        - Admin
      summary: Perform user actions (ban, mute, suspend)
      description: Execute administrative actions on user accounts
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: User ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  enum: [ban, mute, suspend]
                ip:
                  type: string
                  description: Optional IP address to ban
      responses:
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: User not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /admin/roles:
    get:
      tags:
        - Admin
      summary: List all available roles
      description: Get a list of all user roles in the system
      responses:
        '200':
          description: List of roles
  /admin/tags:
    get:
      tags:
        - Admin
      summary: List all tags
      description: Get all file/content tags (not yet implemented)
      responses:
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /admin/tags/{id}:
    post:
      tags:
        - Admin
      summary: Create a new tag
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Tag created successfully
    put:
      tags:
        - Admin
      summary: Update a tag
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - Admin
      summary: Delete a tag
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /admin/dmca:
    get:
      tags:
        - Admin
      summary: List DMCA/takedown requests
      description: Get all DMCA and takedown requests (not yet implemented)
      responses:
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
        - Admin
      summary: Create a DMCA/takedown request
      responses:
        '201':
          description: Takedown request created
  /admin/dmca/{id}:
    put:
      tags:
        - Admin
      summary: Update a DMCA/takedown request
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /admin/file/duplicates:
    get:
      tags:
        - Admin
      summary: Find duplicate files
      description: Search for duplicate files in the system (not yet implemented)
      responses:
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /admin/file/uri-check:
    get:
      tags:
        - Admin
      summary: Check file URIs
      description: Validate and check file URIs (not yet implemented)
      responses:
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /admin/cache/purge:
    post:
      tags:
        - Admin
      summary: Purge server caches
      description: Clear all server caches (not yet implemented)
      responses:
        '201':
          description: Caches purged successfully
  /admin/announcements:
    get:
      tags:
        - Admin
      summary: Get all announcements
      description: Retrieve all announcements for administrators
      responses:
        '200':
          description: List of announcements
    post:
      tags:
        - Admin
      summary: Create a new announcement
      description: Create a new system-wide announcement
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                message:
                  type: string
                severity:
                  type: string
                  enum: [info, warning, error]
              required:
                - title
      responses:
        '201':
          description: Announcement created successfully
        '400':
          description: Title is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /admin/announcements/{uuid}:
    put:
      tags:
        - Admin
      summary: Update an announcement
      description: Update the title, message, or severity of an existing announcement
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
          description: Announcement UUID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                message:
                  type: string
                severity:
                  type: string
                  enum: [info, warning, error]
              required:
                - severity
      responses:
        '204':
          description: Announcement updated successfully
        '400':
          description: Invalid UUID or severity not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Announcement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - Admin
      summary: Delete an announcement
      description: Remove an announcement from the system
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
          description: Announcement UUID
      responses:
        '204':
          description: Announcement deleted successfully
        '400':
          description: Invalid UUID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: User not authorized as admin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Announcement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    User:
      type: object
      properties:
        _id:
          type: string
        username:
          type: string
        email:
          type: string
        roles:
          type: array
          items:
            type: string
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
        oauth:
          type: object
        sessions:
          type: array
          items:
            type: object
    File:
      type: object
      properties:
        _id:
          type: string
        uuid:
          type: string
        name:
          type: string
        type:
          type: string
        size:
          type: number
        mime:
          type: string
        paths:
          type: object
          properties:
            local:
              type: string
            remote:
              type: string
            relative:
              type: string
        collection:
          type: string
        author:
          type: string
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
    Directory:
      type: object
      properties:
        _id:
          type: string
        uuid:
          type: string
        name:
          type: string
        type:
          type: string
        size:
          type: number
        paths:
          type: object
        collection:
          type: string
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
    Announcement:
      type: object
      properties:
        _id:
          type: string
        uuid:
          type: string
        title:
          type: string
        message:
          type: string
        severity:
          type: string
          enum: [info, warning, error]
        author:
          type: string
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
    Pool:
      type: object
      properties:
        _id:
          type: string
        uuid:
          type: string
          description: Unique identifier for the pool
        name:
          type: string
          description: Name of the pool
        description:
          type: string
          description: Optional description of the pool
        tags:
          type: array
          items:
            type: string
          description: Array of tags associated with the pool
        files:
          type: array
          items:
            type: string
          description: Array of file UUIDs contained in the pool
        created:
          type: string
          format: date-time
          description: Timestamp when pool was created
        modified:
          type: string
          format: date-time
          description: Timestamp when pool was last modified
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
    UnauthorizedResponse:
      type: object
      properties:
        error:
          type: string
          description: Unauthorized access message
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: connect.sid
      description: Session cookie for authenticated requests