openapi.yaml

# ============================================================
# Rythmify API — OpenAPI 3.0.3 Specification
# Version: 2.0 (Fixed — April 2026)
# ============================================================

openapi: '3.0.3'

info:
  title: Rythmify API
  description: API for the Rythmify music platform
  version: '2.0'

servers:
  - url: http://localhost:8080/api/v1
    description: Local development server
  - url: https://api.rythmify.com/api/v1
    description: Production server

security:
  - bearerAuth: []

tags:
  - name: Auth
    description: Registration, login, token refresh, and logout
  - name: Users
    description: User profiles, avatars, and account settings
  - name: Tracks
    description: Audio upload, metadata, and track management
  - name: Playback
    description: Playback, player state, queue, and listening-history endpoints.
  - name: Playlists
    description: Create and manage playlists and track ordering
  - name: Comments
    description: Track comments, replies, and comment management
  - name: Feed
    description: Activity feed — Following tab and Discover tab
  - name: Home & Discovery
    description: Personalized home page, stations, mixes, and trending content
  - name: Genre Discovery
    description: Genre page aggregator and paginated sub-endpoints
  - name: Track Discovery
    description: Track-level discovery — related tracks and contextual navigation
  - name: Follow Discovery
    description: Suggested users and artists to follow
  - name: Messages
    description: Direct messaging between users
  - name: Notifications
    description: Real-time alerts for social interactions
  - name: Search
    description: Global search across tracks, users, and playlists
  - name: Follow
    description: Follow, unfollow, followers, following, and suggested users
  - name: Block
    description: Block and unblock users
  - name: Likes
    description: Like and unlike tracks, playlists, and albums. List who liked items and view personal liked libraries.
  - name: Reposts
    description: Repost and remove reposts from tracks, playlists, and albums. List who reposted items and view personal reposted libraries.
  - name: Insights
    description: Creator analytics for uploaded tracks.
  - name: Subscription
    description: Subscription plans, mocked Stripe payments, premium entitlements, and free-plan usage limits.
  - name: Subscriptions - Development Only
    description: Local-development-only subscription testing utilities. These routes are only registered when NODE_ENV=development.
  - name: Moderation
    description: User-facing content reporting for copyright and inappropriate content flags
  - name: Admin
    description: Admin-only endpoints for moderation actions, account management, and platform analytics (requires Admin role)

# ============================================================
# PATHS
# ============================================================
paths:
  # ==========================================================
  # Module 1 — Authentication & User Management
  # ==========================================================

  /auth/register:
    post:
      tags: [Auth]
      summary: Register a new user account
      description: |
        Creates a new user account.
        - CAPTCHA is required to mitigate bot activity.
        - The account role defaults to `listener`.
        - Sends a verification email with a token.
      operationId: registerUser
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthRegisterRequest'
      responses:
        '201':
          description: Account created and verification email sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthRegisterResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '409':
          description: Email already registered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: AUTH_EMAIL_ALREADY_EXISTS
                  message: Email already registered.
        '429':
          $ref: '#/components/responses/RateLimited'

  /auth/check-email:
    post:
      tags: [Auth]
      summary: Check if an email is registered
      description: |
        Checks whether the provided email address is already registered in the system.
        Returns a boolean indicating existence.
      operationId: checkEmailExists
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  description: The email address to check.
      responses:
        '200':
          description: Email existence check successful.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      exists:
                        type: boolean
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'

  /auth/verify-email:
    post:
      description: Confirms a user's email address using the token sent at registration.
      tags: [Auth]
      summary: Verify email address with token
      operationId: verifyEmail
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthVerifyEmailRequest'
      responses:
        '200':
          description: Email verified. Tokens issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthVerifyEmailResponse'
        '400':
          description: Invalid or expired token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: AUTH_TOKEN_INVALID
                  message: Invalid or expired verification token
        '429':
          $ref: '#/components/responses/RateLimited'

  /auth/resend-verification:
    post:
      description: Sends a new email verification token to an unverified account.
      tags: [Auth]
      summary: Resend email verification link
      operationId: resendVerificationEmail
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthResendVerificationRequest'
      responses:
        '200':
          description: Verification email resent (or no-op if not applicable).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
        '400':
          $ref: '#/components/responses/ValidationError'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'

  /auth/login:
    post:
      tags: [Auth]
      summary: Login with email or username
      description: |
        Authenticates a user and issues tokens.
        Returns `access_token` in response body.
        Sets `refresh_token` as HttpOnly cookie.
        Login identifier can be email or username.
      operationId: loginUser
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthLoginRequest'
      responses:
        '200':
          description: Logged in successfully.
          headers:
            Set-Cookie:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthLoginResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          description: Invalid credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: AUTH_INVALID_CREDENTIALS
                  message: Email/username or password incorrect
        '422':
          description: Email not verified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: AUTH_EMAIL_NOT_VERIFIED
                  message: Email must be verified before login
        '403':
          description: Account suspended.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: AUTH_ACCOUNT_SUSPENDED
                  message: Account suspended by admin
        '429':
          $ref: '#/components/responses/RateLimited'

  /auth/refresh:
    post:
      description: Issues a new access token using the HttpOnly refresh token cookie.
      tags: [Auth]
      summary: Refresh access token
      operationId: refreshAccessToken
      security: []
      parameters:
        - name: refresh_token
          in: cookie
          required: true
          schema:
            type: string
      responses:
        '200':
          description: New access token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthRefreshResponse'
        '401':
          description: Invalid/expired refresh token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: AUTH_REFRESH_TOKEN_INVALID
                  message: Refresh token is missing, invalid, or expired
        '403':
          description: Account suspended.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'

  /auth/logout:
    post:
      description: Clears the refresh token cookie, ending the current session.
      tags: [Auth]
      summary: Logout (invalidate refresh token)
      operationId: logoutUser
      security: []
      responses:
        '200':
          description: Logged out successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
        '429':
          $ref: '#/components/responses/RateLimited'

  /auth/forgot-password:
    post:
      description: Sends a password reset link to the provided email address.
      tags: [Auth]
      summary: Request password reset email
      operationId: requestPasswordReset
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthForgotPasswordRequest'
      responses:
        '200':
          description: Password reset email request processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthForgotPasswordResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'

  /auth/reset-password:
    post:
      description: Applies a new password using a valid password reset token.
      tags: [Auth]
      summary: Reset password using reset token
      operationId: resetPassword
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthResetPasswordRequest'
      responses:
        '200':
          description: Password reset successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
        '400':
          $ref: '#/components/responses/ValidationError'
        '422':
          description: Token invalid/expired/used/revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: AUTH_TOKEN_EXPIRED
                  message: Password reset token expired
        '429':
          $ref: '#/components/responses/RateLimited'

  # UNVERIFIED — no matching route found in src/routes/ as of audit date
  # This endpoint (POST /auth/change-password) is referenced in the disconnect flow
  # but does not exist in auth.routes.js. The controller has no changePassword handler.
  /auth/change-password:
    post:
      tags: [Auth]
      summary: Change password for authenticated user
      description: |
        Changes the password for the authenticated user.
        Required before disconnecting an OAuth provider if it is the only login method.
        On success, all active sessions are invalidated (equivalent to logout_all=true).
      operationId: changePassword
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthChangePasswordRequest'
      responses:
        '200':
          description: Password changed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
              example:
                data:
                  success: true
                message: Password changed successfully. Please log in again.
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Current password is incorrect.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: AUTH_INVALID_CREDENTIALS
                  message: Current password is incorrect
        '429':
          $ref: '#/components/responses/RateLimited'

  /auth/change-email:
    post:
      description: Initiates an email change by sending a verification link to the new address.
      tags: [Auth]
      summary: Request email change
      operationId: requestEmailChange
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthChangeEmailRequest'
      responses:
        '200':
          description: Verification email sent to new address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Email already in use.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'

  /auth/verify-email-change:
    post:
      description: Applies a pending email change using the token sent to the new address.
      tags: [Auth]
      summary: Confirm email change using token
      operationId: verifyEmailChange
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthVerifyEmailChangeRequest'
      responses:
        '200':
          description: Email updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthVerifyEmailChangeResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '409':
          description: Email already in use.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Token invalid/expired/used.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'

  /auth/google:
    post:
      description: Authenticates or registers a user via a Google ID token.
      tags: [Auth]
      summary: Login / register with Google
      operationId: googleLogin
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthGoogleLoginRequest'
      responses:
        '200':
          description: Logged in successfully with Google.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthGoogleLoginResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          description: Google token invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Account suspended.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'

  # GitHub OAuth — implemented in auth.routes.js (controllers/auth.controller.js)
  /auth/oauth/github:
    get:
      description: |
        Redirects the browser to the GitHub OAuth consent screen.
        The server constructs the GitHub authorization URL and issues a 302 redirect.
      tags: [Auth]
      summary: Start GitHub OAuth authorization
      operationId: startGithubOAuth
      security: []
      responses:
        '302':
          description: Redirect to GitHub consent screen.
        '429':
          $ref: '#/components/responses/RateLimited'

  /auth/oauth/github/callback:
    get:
      description: |
        Handles the GitHub OAuth redirect. Exchanges the code for a Rythmify access token
        and refresh token, then redirects the browser to the frontend callback URL with
        tokens and user data as query parameters.
      tags: [Auth]
      summary: GitHub OAuth callback
      operationId: githubOAuthCallback
      security: []
      parameters:
        - name: code
          in: query
          required: true
          schema:
            type: string
          description: Authorization code from GitHub.
        - name: state
          in: query
          required: true
          schema:
            type: string
          description: CSRF state token.
        - name: error
          in: query
          required: false
          schema:
            type: string
          description: Present when the user denied access on GitHub.
      responses:
        '302':
          description: |
            Redirect to frontend callback URL. On success, query params include:
            `access_token`, `expires_in`, `is_new_user`, `user_id`, `email`,
            `display_name`, `role`, `is_verified`. On error, redirects with
            `?error=github_denied` or `?error=invalid_params`.
        '429':
          $ref: '#/components/responses/RateLimited'

  # UNVERIFIED — no matching route found in src/routes/ as of audit date
  # SoundCloud OAuth does not exist in auth.routes.js; only GitHub OAuth is implemented.
  /auth/oauth/soundcloud:
    get:
      description: Redirects the browser to the SoundCloud OAuth consent screen.
      tags: [Auth]
      summary: Start SoundCloud OAuth authorization
      operationId: startSoundCloudOAuth
      security: []
      parameters:
        - name: return_to
          in: query
          required: false
          schema:
            type: string
      responses:
        '302':
          description: Redirect to SoundCloud consent screen.

  /auth/oauth/soundcloud/callback:
    get:
      description: Handles the SoundCloud OAuth redirect and issues Rythmify tokens.
      tags: [Auth]
      summary: SoundCloud OAuth callback
      operationId: soundCloudOAuthCallback
      security: []
      parameters:
        - name: code
          in: query
          required: true
          schema:
            type: string
        - name: state
          in: query
          required: true
          schema:
            type: string
        - name: error
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OAuth completed. Tokens issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthLoginResponse'
        '400':
          description: Invalid callback parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: OAuth exchange failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'

  # UNVERIFIED — no matching route found in src/routes/ as of audit date
  # No disconnectOAuthProvider route exists in auth.routes.js.
  /auth/connections/{provider}:
    delete:
      tags: [Auth]
      summary: Disconnect a linked OAuth provider
      description: |
        Unlinks a connected OAuth provider. Returns 422 if this is the only
        login method and no password is set. Set a password first via
        `POST /auth/change-password` before disconnecting.
      operationId: disconnectOAuthProvider
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
            enum: [google, facebook, apple]
      responses:
        '200':
          description: Provider disconnected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No connection found for this provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Cannot disconnect — only login method and no password set.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: BUSINESS_OPERATION_NOT_ALLOWED
                  message: Cannot disconnect the only login method. Set a password first.
        '500':
          $ref: '#/components/responses/InternalError'

  # DELETE /auth/me — implemented in auth.routes.js → auth.controller.deleteAccount
  /auth/me:
    delete:
      description: |
        Permanently deletes the authenticated user's account.
        Requires the user's current password as confirmation.
        Clears both `refreshToken` and `refresh_token` cookies on success.
      tags: [Auth]
      summary: Delete own account
      operationId: deleteAccount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - password
              properties:
                password:
                  type: string
                  description: Current password, required as confirmation before deletion.
      responses:
        '200':
          description: Account deleted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      success:
                        type: boolean
                        example: true
                  message:
                    type: string
                    example: Account deleted successfully.
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  # ==========================================================
  # Module 2 — User Profile & Social Identity
  # ==========================================================

  # GET /users/by-id/{user_id} — alias path for getUserById; same controller as /{user_id}
  /users/by-id/{user_id}:
    get:
      description: |
        Returns the public profile for a given user by UUID. This is an alias for
        `GET /users/{user_id}` that avoids ambiguity with slug-based lookup.
        Optional authentication allows the service to apply privacy rules.
      tags: [Users]
      summary: Get a user profile by UUID (alias path)
      operationId: getUserByIdAlias
      security: []
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: User profile returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicUserResponse'
        '403':
          description: Profile is private.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /users/{user_id}:
    get:
      description: Returns the public profile for a given user, respecting privacy settings.
      tags: [Users]
      summary: Get a user profile by ID
      operationId: getUserById
      security: []
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: User profile returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicUserResponse'
        '403':
          description: Profile is private.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /users/{user_id}/liked-tracks:
    get:
      description: |
        Returns a paginated list of tracks liked by the specified user.
        Bearer authentication may be supplied optionally so private-profile visibility
        and viewer personalization flags can be evaluated for the requester.
      tags: [Users]
      summary: List a user's liked tracks
      operationId: getUserLikedTracks
      security: []
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated liked tracks list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackListResponse'
              example:
                data:
                  - id: e5f6a7b8-c9d0-1234-efab-567890abcdef
                    title: Summer Vibes
                    genre: Electronic
                    duration: 213
                    cover_image: https://cdn.rythmify.com/covers/track1.jpg
                    user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    artist_name: DJ Karim
                    play_count: 4200
                    like_count: 312
                    comment_count: 47
                    repost_count: 19
                    stream_url: https://cdn.rythmify.com/tracks/e5f6a7b8/stream.mp3
                    audio_url: https://cdn.rythmify.com/tracks/e5f6a7b8/audio.mp3
                pagination:
                  limit: 20
                  offset: 0
                  total: 45
                message: User liked tracks fetched successfully
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          description: Target user profile is private and the requester is not allowed to view it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /users/{user_id}/web-profiles:
    get:
      description: |
        Returns a paginated list of web profiles for the specified user.
        Bearer authentication may be supplied optionally to access profiles that you
        are permitted to view. Private profiles return 404 when the requester is not allowed.
      tags: [Users]
      summary: List a user's linked social / web profiles
      operationId: getUserWebProfiles
      security: []
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Web profile list returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebProfileListResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          description: Profile is private and requester is not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /users/me:
    get:
      description: Returns the full authenticated user profile including private fields.
      tags: [Users]
      summary: Get own profile (authenticated)
      operationId: getMyProfile
      responses:
        '200':
          description: Own profile returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OwnProfileFullResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    patch:
      description: Partially updates the authenticated user's public profile fields.
      tags: [Users]
      summary: Edit own profile
      operationId: updateMyProfile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProfileRequest'
      responses:
        '200':
          description: Profile updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OwnProfileFullResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Username already taken.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'

  /me/insights:
    get:
      description: |
        Returns creator insight metrics for tracks uploaded by the authenticated user.
        Buckets are generated in PostgreSQL with `generate_series`, so missing days or months
        are returned with zero counts.
      tags: [Insights]
      summary: Get my creator insights
      operationId: getMyCreatorInsights
      parameters:
        - name: range
          in: query
          required: false
          schema:
            type: string
            enum: [7d, 30d, 12m]
            default: 30d
          description: Time range. `7d` and `30d` return daily buckets; `12m` returns monthly buckets.
        - name: track_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
            nullable: true
          description: Optional owned track filter. Requests for tracks owned by another user return 403.
        - name: timezone
          in: query
          required: false
          schema:
            type: string
            default: UTC
            example: UTC
          description: IANA time zone used for bucket boundaries.
      responses:
        '200':
          description: Creator insights returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatorInsightsResponse'
              example:
                data:
                  range: 30d
                  granularity: day
                  timezone: UTC
                  track_id: null
                  totals:
                    plays: 1200
                    likes: 84
                    comments: 19
                    reposts: 12
                    downloads: 0
                  series:
                    - bucket: '2026-04-01'
                      plays: 40
                      likes: 3
                      comments: 1
                      reposts: 0
                      downloads: 0
                message: Insights fetched successfully.
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

  /users/me/account:
    patch:
      description: Updates birth date and gender for the authenticated user's account.
      tags: [Users]
      summary: Update account settings (birth date, gender)
      operationId: updateMyAccount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAccountRequest'
      responses:
        '200':
          description: Account settings updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OwnProfileFullResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /users/me/role:
    patch:
      description: Switches the authenticated user's role between artist and listener.
      tags: [Users]
      summary: Switch account role (Artist ↔ Listener)
      operationId: switchUserRole
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwitchRoleRequest'
      responses:
        '200':
          description: Role updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OwnProfileResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: User already has the requested role.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'

  /users/me/avatar:
    post:
      description: Uploads and stores a new profile picture, replacing any existing one.
      tags: [Users]
      summary: Upload or replace profile picture
      operationId: uploadAvatar
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AvatarUploadRequest'
      responses:
        '200':
          description: Avatar uploaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvatarUploadResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          $ref: '#/components/responses/FileTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      description: Removes the current profile picture and resets the field to null.
      tags: [Users]
      summary: Remove profile picture
      operationId: deleteAvatar
      responses:
        '200':
          description: Profile picture removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /users/me/cover:
    post:
      description: Uploads and stores a new cover photo, replacing any existing one.
      tags: [Users]
      summary: Upload or replace cover photo
      operationId: uploadCover
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CoverUploadRequest'
      responses:
        '200':
          description: Cover photo uploaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoverUploadResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          $ref: '#/components/responses/FileTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      description: Removes the current cover photo and resets the field to null.
      tags: [Users]
      summary: Remove cover photo
      operationId: deleteCover
      responses:
        '200':
          description: Cover photo removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /users/me/web-profiles:
    get:
      description: Returns all external social links saved by the authenticated user.
      tags: [Users]
      summary: List linked social / web profiles
      operationId: listWebProfiles
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Web profile list returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebProfileListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      description: Adds a new external social or website link to the user's profile.
      tags: [Users]
      summary: Add a social / web profile link
      operationId: addWebProfile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddWebProfileRequest'
      responses:
        '201':
          description: Web profile link created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebProfileCreatedResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: A profile for this platform already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'

  /users/me/web-profiles/{profile_id}:
    delete:
      description: Removes a specific external social link by its ID.
      tags: [Users]
      summary: Remove a linked social / web profile
      operationId: deleteWebProfile
      parameters:
        - name: profile_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Web profile removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /users/me/privacy:
    patch:
      description: Sets the is_private flag on the authenticated user's profile.
      tags: [Users]
      summary: Toggle profile public / private visibility
      operationId: updatePrivacy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePrivacyRequest'
      responses:
        '200':
          description: Privacy setting updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatePrivacyResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /users/me/privacy-settings:
    get:
      description: Returns all five privacy toggle flags for the authenticated user.
      tags: [Users]
      summary: Get all privacy settings
      operationId: getMyPrivacySettings
      responses:
        '200':
          description: Privacy settings returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivacySettingsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    patch:
      description: Partially updates the authenticated user's privacy toggle flags.
      tags: [Users]
      summary: Update privacy settings
      operationId: updateMyPrivacySettings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePrivacySettingsRequest'
      responses:
        '200':
          description: Privacy settings updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivacySettingsResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /users/me/genres:
    get:
      description: Returns the list of genres the authenticated user has saved as favorites.
      tags: [Users]
      summary: Get saved favorite genres
      operationId: getMyGenres
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Favorite genres returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenresResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      description: Replaces the authenticated user's entire saved genre list.
      tags: [Users]
      summary: Replace the full list of favorite genres
      operationId: replaceMyGenres
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplaceGenresRequest'
      responses:
        '200':
          description: Genres updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenresResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /users/me/stations:
    get:
      description: Get a list of stations saved by the current user.
      tags: [Stations]
      summary: Get saved stations
      operationId: getUserSavedStations
      parameters:
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
        - name: limit
          in: query
          schema: { type: integer, default: 20, minimum: 1, maximum: 50 }
      responses:
        '200':
          description: Saved stations returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedStationsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/me/onboarding:
    patch:
      description: Completes missing profile fields for a new Google Sign-In account.
      tags: [Users]
      summary: Complete profile onboarding after Google sign-in
      operationId: completeGoogleOnboarding
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteGoogleOnboardingRequest'
      responses:
        '200':
          description: Onboarding completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompleteGoogleOnboardingResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Onboarding already completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'

  # ==========================================================
  # Module 4 — Audio Upload & Track Management
  # ==========================================================

  /tags:
    get:
      description: Returns all available platform tags in alphabetical order.
      tags: [Tracks]
      summary: Get all available platform tags
      operationId: listTags
      security: []
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Tags fetched successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagListResponse'
        '500':
          $ref: '#/components/responses/InternalError'

  /genres:
    get:
      tags: [Tracks]
      summary: Get all available platform genres
      description: |
        Returns the complete list of genres. Used by the Search/Vibes tab to
        populate the genre grid. Cache this result for 1 hour client-side.
      operationId: listGenres
      security: []
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Genres fetched successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenreListResponse'
        '500':
          $ref: '#/components/responses/InternalError'

  /tracks:
    post:
      description: |
        Uploads an audio file and creates a new track record for the authenticated user.

        Subscription limits:
        - Free users may upload up to 3 tracks.
        - Premium users have unlimited uploads.
        - If the user's effective plan does not allow more uploads, this endpoint returns 403 with code `SUBSCRIPTION_LIMIT_REACHED`.
      tags: [Tracks]
      summary: Upload a new audio track
      operationId: uploadTrack
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadTrackRequest'
      responses:
        '201':
          description: Track created and queued for processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadTrackResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Free plan track upload limit reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: SUBSCRIPTION_LIMIT_REACHED
                  message: Free plan track upload limit reached. Upgrade to premium for unlimited uploads.
        '413':
          $ref: '#/components/responses/FileTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /tracks/me:
    get:
      description: |
        Returns all tracks owned by the authenticated user, including private ones.
        Geo-restricted tracks remain visible, but audio-related URLs may be null when playback is not available for `X-Country-Code`.
      tags: [Tracks]
      summary: List authenticated user's own tracks
      operationId: getMyTracks
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 20, minimum: 1, maximum: 100 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/TrackStatus'
        - $ref: '#/components/parameters/XCountryCode'
      responses:
        '200':
          description: Paginated list of own tracks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MyTrackListResponse'
              example:
                data:
                  - id: e5f6a7b8-c9d0-1234-efab-567890abcdef
                    title: Summer Vibes
                    genre: Electronic
                    duration: 213
                    cover_image: https://cdn.rythmify.com/covers/track1.jpg
                    user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    artist_name: DJ Karim
                    play_count: 4200
                    like_count: 312
                    comment_count: 47
                    repost_count: 19
                    stream_url: https://cdn.rythmify.com/tracks/e5f6a7b8/stream.mp3
                    is_liked_by_me: true
                pagination:
                  limit: 20
                  offset: 0
                  total: 1
                message: My tracks fetched successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /tracks/{track_id}:
    get:
      description: |
        Returns full metadata for a single track by its ID.
        This endpoint remains public and accepts authentication optionally.
        When a viewer is authenticated, the response personalizes
        `is_liked_by_me`, `is_reposted_by_me`, and `is_artist_followed_by_me`
        for that viewer. Anonymous requests receive `false` for all three fields.
        Geo-restricted tracks remain visible, but `audio_url`, `stream_url`, `preview_url`,
        and `waveform_url` may be null with `playback_restriction_reason: region_restricted`.
      tags: [Tracks]
      summary: Get track details by ID
      operationId: getTrack
      security: []
      parameters:
        - $ref: '#/components/parameters/TrackId'
        - name: secret_token
          in: query
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/XCountryCode'
      responses:
        '200':
          description: Track details returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackResponse'
              example:
                data:
                  id: e5f6a7b8-c9d0-1234-efab-567890abcdef
                  title: Summer Vibes
                  description: Sunset house set recorded live in Cairo.
                  genre: Electronic
                  tags: [house, sunset]
                  duration: 213
                  file_size: 8457210
                  bitrate: 320
                  status: ready
                  is_public: true
                  is_hidden: false
                  user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  artist_name: DJ Karim
                  play_count: 4200
                  like_count: 312
                  comment_count: 47
                  repost_count: 19
                  is_liked_by_me: true
                  is_reposted_by_me: false
                  is_artist_followed_by_me: true
                  audio_url: https://cdn.rythmify.com/tracks/e5f6a7b8/audio.mp3
                  stream_url: https://cdn.rythmify.com/tracks/e5f6a7b8/stream.mp3
                  preview_url: https://cdn.rythmify.com/tracks/e5f6a7b8/preview.mp3
                  waveform_url: https://cdn.rythmify.com/tracks/e5f6a7b8/waveform.json
                  cover_image: https://cdn.rythmify.com/covers/track1.jpg
                  buy_link: null
                  record_label: Desert Pulse
                  publisher: Desert Pulse
                  release_date: '2026-03-01'
                  isrc: EG-A1B-26-00001
                  p_line: (P) 2026 DJ Karim
                  explicit_content: false
                  include_in_rss_feed: true
                  display_embed_code: true
                  enable_app_playback: true
                  enable_downloads: false
                  enable_offline_listening: false
                  license_type: all_rights_reserved
                  allow_comments: true
                  show_comments_public: true
                  show_insights_public: true
                  geo_restriction_type: worldwide
                  geo_regions: []
                  is_geo_blocked: false
                  playback_restriction_reason: null
                  created_at: '2026-03-01T10:00:00Z'
                  updated_at: '2026-03-02T12:30:00Z'
                message: Track fetched successfully
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    patch:
      description: Partially updates metadata fields for the specified track.
      tags: [Tracks]
      summary: Update track metadata
      operationId: updateTrack
      parameters:
        - $ref: '#/components/parameters/TrackId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTrackRequest'
      responses:
        '200':
          description: Track metadata updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      description: Soft-deletes a track by marking it deleted while preserving stored assets and related rows.
      tags: [Tracks]
      summary: Delete a track
      operationId: deleteTrack
      parameters:
        - $ref: '#/components/parameters/TrackId'
      responses:
        '204':
          description: Track deleted. No response body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /tracks/{track_id}/cover:
    patch:
      description: Uploads or replaces the cover image for a track owned by the authenticated user.
      tags: [Tracks]
      summary: Update track cover image
      operationId: updateTrackCoverImage
      parameters:
        - $ref: '#/components/parameters/TrackId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UpdateTrackCoverImageRequest'
      responses:
        '200':
          description: Track cover image updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/FileTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /tracks/{track_id}/audio:
    patch:
      description: |
        Replaces the original audio file for a track owned by the authenticated user,
        resets audio-derived processing fields, and restarts background processing.
        Existing storage objects are not deleted by this operation.
      tags: [Tracks]
      summary: Replace track audio
      operationId: updateTrackAudio
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/TrackId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UpdateTrackAudioRequest'
      responses:
        '200':
          description: Track audio updated and processing restarted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackResponse'
              example:
                data:
                  id: e5f6a7b8-c9d0-1234-efab-567890abcdef
                  title: Summer Vibes
                  audio_url: https://cdn.rythmify.com/tracks/a1b2c3d4/new-audio.mp3
                  status: processing
                  stream_url: null
                  waveform_url: null
                  preview_url: null
                  duration: null
                  bitrate: null
                  file_size: 8457210
                  cover_image: https://cdn.rythmify.com/covers/track1.jpg
                  user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  artist_name: DJ Karim
                message: Track audio updated successfully. Processing restarted.
        '400':
          description: Missing audio_file or validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: VALIDATION_FAILED
                  message: Audio file is required
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/FileTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /tracks/{track_id}/stream:
    get:
      description: Returns the CDN streaming URL for the specified track. Returns 403 when playback is region-restricted for `X-Country-Code`.
      tags: [Tracks]
      summary: Get streaming URL for a track
      operationId: getTrackStreamUrl
      security: []
      parameters:
        - $ref: '#/components/parameters/TrackId'
        - name: secret_token
          in: query
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/XCountryCode'
      responses:
        '200':
          description: Streaming URL returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackStreamResponse'
        '202':
          description: Track still processing — retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/TrackProcessingFailed'
        '500':
          $ref: '#/components/responses/InternalError'

  /tracks/{track_id}/offline-download:
    get:
      description: |
        This is a premium subscription feature. It validates the user's active
        subscription and track offline-listening settings before returning a safe
        playable download URL.
        The backend validates access and entitlement, but does not proxy or download the audio file.
        `stream_url` is used when available; otherwise `audio_url` is used as a fallback.
        Returns 403 when playback is region-restricted for `X-Country-Code`.
      tags: [Subscription, Tracks]
      summary: Get offline download URL for a premium track
      operationId: getTrackOfflineDownload
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/TrackId'
        - name: secret_token
          in: query
          required: false
          description: Optional private share token for private tracks.
          schema:
            type: string
        - $ref: '#/components/parameters/XCountryCode'
      responses:
        '200':
          description: Offline download URL returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackOfflineDownloadResponse'
              example:
                data:
                  track_id: e5f6a7b8-c9d0-1234-efab-567890abcdef
                  download_url: https://cdn.rythmify.com/tracks/e5f6a7b8/stream.mp3?sig=mock
                  source: stream
                  expires_in_seconds: 300
                  expires_at: '2026-04-25T12:05:00Z'
                message: Offline download URL fetched successfully.
        '202':
          description: Track still processing — retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Premium subscription required, offline listening disabled, or private access denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/TrackProcessingFailed'
        '500':
          $ref: '#/components/responses/InternalError'

  /tracks/{track_id}/waveform:
    get:
      description: Returns normalized amplitude peak data for waveform rendering. Returns 403 when playback is region-restricted for `X-Country-Code`.
      tags: [Tracks]
      summary: Get waveform peak data for a track
      operationId: getTrackWaveform
      security: []
      parameters:
        - $ref: '#/components/parameters/TrackId'
        - $ref: '#/components/parameters/XCountryCode'
      responses:
        '200':
          description: Waveform peak data returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackWaveformResponse'
        '202':
          description: Waveform not yet generated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/TrackProcessingFailed'

  /tracks/{track_id}/fan-leaderboard:
    get:
      description: |
        Returns up to 5 top fans for a track, ranked by play count for the selected period.
        `overall` uses all-time plays.
        `first_7_days` uses the fixed first 7 days starting from the track release window,
        anchored to `release_date` when present, otherwise `created_at`.
        `last_7_days` is still accepted temporarily as a deprecated backward-compatible alias.
      tags: [Tracks]
      summary: Get top fans for a track
      operationId: getTrackFanLeaderboard
      security: []
      parameters:
        - $ref: '#/components/parameters/TrackId'
        - name: period
          in: query
          required: false
          description: |
            `overall` ranks fans using all-time plays.
            `first_7_days` ranks fans using only plays with timestamps from the track release window:
            `played_at >= window_start` and `played_at < window_start + 7 days`,
            where `window_start` is `release_date` when present, otherwise `created_at`.
            `last_7_days` is still accepted temporarily as a deprecated alias, but responses always return `first_7_days`.
          schema:
            type: string
            enum: [overall, first_7_days]
            default: overall
        - name: secret_token
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Fan leaderboard returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FanLeaderboardResponse'
              example:
                data:
                  period: first_7_days
                  items:
                    - rank: 1
                      user:
                        id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                        username: soundwave_cairo
                        display_name: Soundwave
                        profile_picture: https://cdn.rythmify.com/avatars/user123.jpg
                        is_verified: true
                      play_count: 37
                      last_played_at: '2026-04-09T08:30:00Z'
                    - rank: 2
                      user:
                        id: b2c3d4e5-f6a7-8901-bcde-f23456789012
                        username: late_night_loops
                        display_name: Late Night Loops
                        profile_picture: null
                        is_verified: false
                      play_count: 24
                      last_played_at: '2026-04-08T22:10:00Z'
                message: Fan leaderboard fetched successfully.
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /tracks/{track_id}/visibility:
    patch:
      description: Sets the is_public flag on a track to control its discoverability.
      tags: [Tracks]
      summary: Toggle track visibility (public / private)
      operationId: updateTrackVisibility
      parameters:
        - $ref: '#/components/parameters/TrackId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTrackVisibilityRequest'
      responses:
        '200':
          description: Track visibility updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateTrackVisibilityResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /tracks/{track_id}/share-link:
    get:
      tags: [Tracks]
      summary: Get private share link for a track
      description: |
        Returns the private share link for a track.
        Owner only.
        Only available for private tracks.
      operationId: getPrivateShareLink
      parameters:
        - $ref: '#/components/parameters/TrackId'
      responses:
        '200':
          description: Private share link fetched successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateShareLinkResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /users/{user_id}/tracks:
    get:
      description: |
        Returns paginated public tracks uploaded by the specified user.
        Geo-restricted tracks remain visible, but playable URLs may be null for `X-Country-Code`.
      tags: [Tracks]
      summary: List all public tracks by a user
      operationId: getUserTracks
      security: []
      parameters:
        - $ref: '#/components/parameters/UserId'
        - name: limit
          in: query
          schema: { type: integer, default: 20, minimum: 1, maximum: 100 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
        - $ref: '#/components/parameters/XCountryCode'
      responses:
        '200':
          description: Paginated list of user's public tracks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackListResponse'
              example:
                data:
                  - id: e5f6a7b8-c9d0-1234-efab-567890abcdef
                    title: Summer Vibes
                    genre: Electronic
                    duration: 213
                    cover_image: https://cdn.rythmify.com/covers/track1.jpg
                    user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    artist_name: DJ Karim
                    play_count: 4200
                    like_count: 312
                    comment_count: 47
                    repost_count: 19
                    stream_url: https://cdn.rythmify.com/tracks/e5f6a7b8/stream.mp3
                pagination:
                  limit: 20
                  offset: 0
                  total: 1
                message: User tracks fetched successfully
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  # ==========================================================
  # Module 5 — Playback & Streaming Engine
  # ==========================================================

  /tracks/{track_id}/playback-state:
    get:
      description: |
        Returns the playback access level for the requesting user without triggering a play event.
        Geo-blocked tracks return `state: blocked`, null playback URLs, and `reason: region_restricted`.
      tags: [Playback]
      summary: Check playability for the requesting user
      operationId: getPlaybackState
      security: []
      parameters:
        - $ref: '#/components/parameters/TrackId'
        - $ref: '#/components/parameters/XCountryCode'
      responses:
        '200':
          description: Playback access level returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaybackStateResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /tracks/{track_id}/play:
    post:
      description: |
        Increments play count and returns the appropriate stream or preview URL.
        Region-restricted requests return 403 and do not record listening history or increment play count.
      tags: [Playback]
      summary: Record a play event and get stream URL
      operationId: recordPlayEvent
      security: []
      parameters:
        - $ref: '#/components/parameters/TrackId'
        - $ref: '#/components/parameters/XCountryCode'
      responses:
        '200':
          description: Playback access granted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordPlayResponse'
        '202':
          description: Track still processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/TrackProcessingFailed'
        '500':
          $ref: '#/components/responses/InternalError'

  /me/player/state:
    get:
      description: Retrieves the authenticated user's last persisted player state. Track URLs in the current item or queue may be null when region-restricted for `X-Country-Code`.
      tags: [Playback]
      summary: Get last saved player state
      operationId: getPlayerState
      parameters:
        - $ref: '#/components/parameters/XCountryCode'
      responses:
        '200':
          description: Player state returned. data is null if no state saved yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerStateResponse'
              example:
                data:
                  track_id: 63f8f162-b255-4525-bf71-9913541cbbc5
                  track_title: Midnight City Lights
                  artist_name: DJ Nova
                  stream_url: https://cdn.rythmify.app/tracks/63f8f162-b255-4525-bf71-9913541cbbc5/stream.mp3
                  duration: 182
                  cover_image: https://cdn.rythmify.app/covers/example.jpg
                  position_seconds: 1473.8
                  volume: 0.49
                  queue:
                    - queue_item_id: 5ef3df1d-c7fe-4f59-a00a-7a987ac14fef
                      track_id: 39c7c3c3-7d02-4ac1-a647-a2fa0401de02
                      queue_bucket: next_up
                      source_type: track
                      source_id: null
                      source_title: null
                      source_position: null
                      added_at: '2026-04-18T20:00:18.294Z'
                      stream_url: https://cdn.rythmify.app/tracks/39c7c3c3-7d02-4ac1-a647-a2fa0401de02/stream.mp3
                      track_title: First Light
                      artist_name: Aurora Lane
                      duration: 201
                      cover_image: https://cdn.rythmify.app/covers/example.jpg
                    - queue_item_id: e85d14f1-98eb-462d-b3f0-4f7f78cc8c7c
                      track_id: 91d42a97-cb47-429e-b9e3-88fbff4e2680
                      queue_bucket: context
                      source_type: playlist
                      source_id: 4b28f3dd-2875-4811-aaf1-4fda7d3d113c
                      source_title: My Running Mix
                      source_position: 5
                      added_at: '2026-04-18T20:00:19.000Z'
                      stream_url: https://cdn.rythmify.app/tracks/91d42a97-cb47-429e-b9e3-88fbff4e2680/stream.mp3
                      track_title: Runaway Pulse
                      artist_name: Echo Atlas
                      duration: 219
                      cover_image: https://cdn.rythmify.app/covers/example.jpg
                  saved_at: '2026-04-18T20:00:20.000Z'
                message: Player state fetched successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      description: |
        Persists the authenticated user's current player queue and resume position.

        After saving player state, the backend also performs a best-effort analytics enrichment:
        it looks for the most recent matching listening-history entry for the same user and track
        and updates that row's stored progress using the furthest known position reached.

        Notes:
        - This endpoint does not create listening-history rows.
        - If no matching listening-history entry exists, player state still saves successfully.
        - Backward seeking updates the saved player position, but never reduces stored
          listening-history progress.
        - Requests accept legacy queue track UUID-formatted strings and rich queue-item objects.
        - Responses always return normalized queue-item objects. Track URLs in the response
          may be null when region-restricted for `X-Country-Code`.
      tags: [Playback]
      summary: Save persistent player state
      operationId: savePlayerState
      parameters:
        - $ref: '#/components/parameters/XCountryCode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavePlayerStateRequest'
            example:
              track_id: 63f8f162-b255-4525-bf71-9913541cbbc5
              position_seconds: 1473.8
              volume: 0.49
              queue:
                - track_id: 39c7c3c3-7d02-4ac1-a647-a2fa0401de02
                - queue_item_id: e85d14f1-98eb-462d-b3f0-4f7f78cc8c7c
                  track_id: 91d42a97-cb47-429e-b9e3-88fbff4e2680
                  queue_bucket: context
                  source_type: playlist
                  source_id: 4b28f3dd-2875-4811-aaf1-4fda7d3d113c
                  source_title: My Running Mix
                  source_position: 5
                  added_at: '2026-04-18T20:00:19.000Z'
      responses:
        '200':
          description: Player state saved. Matching listening-history progress may also be enriched best-effort.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerStateResponse'
              example:
                data:
                  track_id: 63f8f162-b255-4525-bf71-9913541cbbc5
                  track_title: Midnight City Lights
                  artist_name: DJ Nova
                  stream_url: https://cdn.rythmify.app/tracks/63f8f162-b255-4525-bf71-9913541cbbc5/stream.mp3
                  duration: 182
                  cover_image: https://cdn.rythmify.app/covers/example.jpg
                  position_seconds: 1473.8
                  volume: 0.49
                  queue:
                    - queue_item_id: 5ef3df1d-c7fe-4f59-a00a-7a987ac14fef
                      track_id: 39c7c3c3-7d02-4ac1-a647-a2fa0401de02
                      queue_bucket: next_up
                      source_type: track
                      source_id: null
                      source_title: null
                      source_position: null
                      added_at: '2026-04-18T20:00:18.294Z'
                      stream_url: https://cdn.rythmify.app/tracks/39c7c3c3-7d02-4ac1-a647-a2fa0401de02/stream.mp3
                      track_title: First Light
                      artist_name: Aurora Lane
                      duration: 201
                      cover_image: https://cdn.rythmify.app/covers/example.jpg
                    - queue_item_id: e85d14f1-98eb-462d-b3f0-4f7f78cc8c7c
                      track_id: 91d42a97-cb47-429e-b9e3-88fbff4e2680
                      queue_bucket: context
                      source_type: playlist
                      source_id: 4b28f3dd-2875-4811-aaf1-4fda7d3d113c
                      source_title: My Running Mix
                      source_position: 5
                      added_at: '2026-04-18T20:00:19.000Z'
                      stream_url: https://cdn.rythmify.app/tracks/91d42a97-cb47-429e-b9e3-88fbff4e2680/stream.mp3
                      track_title: Runaway Pulse
                      artist_name: Echo Atlas
                      duration: 219
                      cover_image: https://cdn.rythmify.app/covers/example.jpg
                  saved_at: '2026-04-18T20:00:20.000Z'
                message: Player state saved successfully.
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /me/player/queue/items/{queue_item_id}:
    delete:
      description: |
        Removes one specific upcoming queue occurrence by `queue_item_id`.
        `track_id` is not sufficient because duplicate queued tracks are allowed.
        Returns the updated normalized queue without changing the current
        `track_id`, `position_seconds`, or `volume`. Track URLs in the response
        may be null when region-restricted for `X-Country-Code`.
      tags: [Playback]
      summary: Remove one queue item
      operationId: removeQueueItem
      parameters:
        - $ref: '#/components/parameters/QueueItemId'
        - $ref: '#/components/parameters/XCountryCode'
      responses:
        '200':
          description: Updated upcoming queue returned after removing the requested item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerQueueResponse'
              example:
                data:
                  queue:
                    - queue_item_id: e85d14f1-98eb-462d-b3f0-4f7f78cc8c7c
                      track_id: 91d42a97-cb47-429e-b9e3-88fbff4e2680
                      queue_bucket: context
                      source_type: playlist
                      source_id: 4b28f3dd-2875-4811-aaf1-4fda7d3d113c
                      source_title: My Running Mix
                      source_position: 5
                      added_at: '2026-04-18T20:00:19.000Z'
                      stream_url: https://cdn.rythmify.app/tracks/91d42a97-cb47-429e-b9e3-88fbff4e2680/stream.mp3
                      track_title: Runaway Pulse
                      artist_name: Echo Atlas
                      duration: 219
                      cover_image: https://cdn.rythmify.app/covers/example.jpg
                message: Queue updated successfully.
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /me/player/queue:
    delete:
      description: |
        Clears the authenticated user's entire upcoming queue while preserving the current
        `track_id`, `position_seconds`, and `volume`.
        If no player state exists or the stored queue is already empty, the endpoint still
        succeeds and returns an empty queue.
      tags: [Playback]
      summary: Clear the upcoming queue
      operationId: clearPlayerQueue
      responses:
        '200':
          description: Queue cleared successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerQueueResponse'
              example:
                data:
                  queue: []
                message: Queue cleared successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    patch:
      description: |
        Reorders the authenticated user's existing queue by `queue_item_id`.
        The request must be a full permutation of the current queue snapshot:
        every current `queue_item_id` must appear exactly once, and `position`
        values are 1-based and must form a complete contiguous set from `1..N`.
        The endpoint preserves every queue item object exactly and only changes
        the array order. It does not change `track_id`, `position_seconds`, or `volume`.
        Track URLs in the response may be null when region-restricted for `X-Country-Code`.
      tags: [Playback]
      summary: Reorder queue items
      operationId: reorderPlayerQueue
      parameters:
        - $ref: '#/components/parameters/XCountryCode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueueReorderRequest'
            example:
              items:
                - queue_item_id: e85d14f1-98eb-462d-b3f0-4f7f78cc8c7c
                  position: 1
                - queue_item_id: 5ef3df1d-c7fe-4f59-a00a-7a987ac14fef
                  position: 2
      responses:
        '200':
          description: Queue reordered successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerQueueResponse'
              example:
                data:
                  queue:
                    - queue_item_id: 5ef3df1d-c7fe-4f59-a00a-7a987ac14fef
                      track_id: 39c7c3c3-7d02-4ac1-a647-a2fa0401de02
                      queue_bucket: next_up
                      source_type: track
                      source_id: null
                      source_title: null
                      source_position: null
                      added_at: '2026-04-18T20:00:18.294Z'
                      stream_url: https://cdn.rythmify.app/tracks/39c7c3c3-7d02-4ac1-a647-a2fa0401de02/stream.mp3
                      track_title: First Light
                      artist_name: Aurora Lane
                      duration: 201
                      cover_image: https://cdn.rythmify.app/covers/example.jpg
                    - queue_item_id: e85d14f1-98eb-462d-b3f0-4f7f78cc8c7c
                      track_id: 91d42a97-cb47-429e-b9e3-88fbff4e2680
                      queue_bucket: context
                      source_type: playlist
                      source_id: 4b28f3dd-2875-4811-aaf1-4fda7d3d113c
                      source_title: My Running Mix
                      source_position: 5
                      added_at: '2026-04-18T20:00:19.000Z'
                      stream_url: https://cdn.rythmify.app/tracks/91d42a97-cb47-429e-b9e3-88fbff4e2680/stream.mp3
                      track_title: Runaway Pulse
                      artist_name: Echo Atlas
                      duration: 219
                      cover_image: https://cdn.rythmify.app/covers/example.jpg
                message: Queue updated successfully.
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /me/player/queue/context:
    post:
      description: |
        High-level summary
        - Resolves a supported playback context into playable tracks and applies it to the
          authenticated user's saved player state.
        - Non-playable tracks are skipped before queue insertion, including blocked,
          processing, failed, unavailable, private/inaccessible/missing, and geo-blocked
          tracks for `X-Country-Code`.
        - If all resolved tracks are skipped, the endpoint returns `404 QUEUE_CONTEXT_EMPTY`.
        - The returned queue is normalized into queue items with provenance metadata so
          clients can render both playback ordering and source labels consistently.

        Interaction behavior
        - `interaction_type=play` starts the resolved context immediately, sets the
          current track to the first resolved track, creates or replaces the single
          active play context, preserves all current `next_up` items, and removes the
          previous `context` bucket.
        - The active play context is represented by the current `track_id` plus the
          remaining resolved tracks stored as `queue_bucket=context` items.
        - Starting a new play context removes only old `queue_bucket=context` items.
          Items in `queue_bucket=next_up` are preserved even when their `source_type`
          is `playlist`, `album`, `mix`, `genre`, `liked_tracks`, or another context
          source.
        - Re-sending the same loaded play context is idempotent. The backend returns
          the current player state without duplicating queue items, rebuilding
          `queue_item_id` values, resetting `position_seconds`, or updating the saved
          player state row.
        - `interaction_type=next_up` preserves the current track, appends the resolved
          items to the end of the `next_up` bucket, and keeps the existing `context`
          bucket behind them.
        - Duplicate tracks are allowed and each occurrence gets its own `queue_item_id`.

        Supported source types
        - `track`: queue one direct track into `next_up` by `source_id`. This source type
          only supports `interaction_type=next_up`.
        - `playlist`: resolve tracks from a playlist identified by `source_id`.
        - `album`: resolve tracks from an album identified by `source_id`.
        - `mix`: resolve tracks from a mix identified by `source_id`. Mix ids may be
          non-UUID strings such as `daily:for-you`.
        - `station`: resolve tracks from a station identified by `source_id`.
        - `genre`: resolve tracks from a genre identified by `source_id`.
        - `liked_tracks`: resolve a user's liked tracks. Uses `target_user_id` when
          provided and otherwise defaults to the authenticated user.
        - `listening_history`: resolve the authenticated user's listening history.
          This source is self-only.
        - `reposts`: resolve a user's reposted tracks. Uses `target_user_id` when
          provided and otherwise defaults to the authenticated user.
        - `user_tracks`: resolve tracks uploaded by a user. Uses `target_user_id` when
          provided and otherwise defaults to the authenticated user.

        Parameter rules
        - `source_id` is required for `track`, `playlist`, `album`, `mix`, `station`,
          and `genre`.
        - `source_id` is usually omitted or `null` for `liked_tracks`,
          `listening_history`, `reposts`, and `user_tracks`.
        - For `source_type=track`, `source_id` must be the track UUID to queue.
        - Do not assume `source_id` is always a UUID. Mix contexts may use string keys.
        - `target_user_id` is optional for `liked_tracks`, `reposts`, and
          `user_tracks`, and defaults to the authenticated user when omitted.
        - `target_user_id` should be omitted or `null` for `track`, `playlist`, `album`,
          `mix`, `station`, and `genre`.
        - `listening_history` is self-only. Requesting another user's history through
          this endpoint is not allowed.
        - `source_type=track` does not support `interaction_type=play`.

        Response interpretation for FE
        - `source_type` describes where a returned queue item was resolved from.
        - `queue_bucket` describes where that queue item now lives in playback ordering:
          `next_up` or `context`.
        - These fields are not interchangeable. A `genre` or `playlist` resolved with
          `interaction_type=next_up` still keeps its real `source_type` while living in
          `queue_bucket=next_up`.
        - A direct single-track queue action keeps `source_type=track`. It is not
          converted into a context source type.
        - Use `source_type` together with `source_title` for provenance labels.
        - Use `queue_bucket` for ordering logic and visual grouping in the queue UI.
      tags: [Playback]
      summary: Apply a playback context to the player queue
      operationId: addQueueContext
      parameters:
        - $ref: '#/components/parameters/XCountryCode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueueContextRequest'
            examples:
              playPlaylist:
                summary: Play a playlist now
                value:
                  interaction_type: play
                  source_type: playlist
                  source_id: 4b28f3dd-2875-4811-aaf1-4fda7d3d113c
                  target_user_id: null
              playAlbum:
                summary: Play an album now
                value:
                  interaction_type: play
                  source_type: album
                  source_id: 1b9a4d54-76d3-40c6-b4d9-1dd0c518f3e2
                  target_user_id: null
              nextUpTrack:
                summary: Add one direct track to next up
                value:
                  interaction_type: next_up
                  source_type: track
                  source_id: 39c7c3c3-7d02-4ac1-a647-a2fa0401de02
                  target_user_id: null
              nextUpMix:
                summary: Add a mix to next up
                value:
                  interaction_type: next_up
                  source_type: mix
                  source_id: daily:for-you
                  target_user_id: null
              nextUpStation:
                summary: Add a station to next up
                value:
                  interaction_type: next_up
                  source_type: station
                  source_id: 61cb32ef-14d9-4ef6-8c54-0d8f0a6d0af5
                  target_user_id: null
              nextUpGenre:
                summary: Add a genre context to next up
                value:
                  interaction_type: next_up
                  source_type: genre
                  source_id: 6c6d6f9f-2e4a-4c0e-84e6-1738a29edb8d
                  target_user_id: null
              likedTracksDefaultSelf:
                summary: Queue my liked tracks without sending target_user_id
                value:
                  interaction_type: next_up
                  source_type: liked_tracks
                  source_id: null
                  target_user_id: null
              playListeningHistory:
                summary: Play my listening history
                value:
                  interaction_type: play
                  source_type: listening_history
                  source_id: null
                  target_user_id: null
              nextUpRepostsForUser:
                summary: Add another user's reposts to next up
                value:
                  interaction_type: next_up
                  source_type: reposts
                  source_id: null
                  target_user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              playUserTracks:
                summary: Play a user's uploaded tracks
                value:
                  interaction_type: play
                  source_type: user_tracks
                  source_id: null
                  target_user_id: c8db3fbe-4d32-4c0a-b592-9b9ef4fd2e51
      responses:
        '200':
          description: Full normalized player state returned after applying the requested context.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerStateResponse'
              examples:
                playAlbum:
                  summary: Playing an album replaces the old context bucket
                  value:
                    data:
                      track_id: 63f8f162-b255-4525-bf71-9913541cbbc5
                      track_title: Midnight City Lights
                      artist_name: DJ Nova
                      stream_url: https://cdn.rythmify.app/tracks/63f8f162-b255-4525-bf71-9913541cbbc5/stream.mp3
                      duration: 182
                      cover_image: https://cdn.rythmify.app/covers/example.jpg
                      position_seconds: 0
                      volume: 0.49
                      queue:
                        - queue_item_id: 5ef3df1d-c7fe-4f59-a00a-7a987ac14fef
                          track_id: 39c7c3c3-7d02-4ac1-a647-a2fa0401de02
                          queue_bucket: next_up
                          source_type: track
                          source_id: null
                          source_title: null
                          source_position: null
                          added_at: '2026-04-18T20:00:18.294Z'
                          stream_url: https://cdn.rythmify.app/tracks/39c7c3c3-7d02-4ac1-a647-a2fa0401de02/stream.mp3
                          track_title: First Light
                          artist_name: Aurora Lane
                          duration: 201
                          cover_image: https://cdn.rythmify.app/covers/example.jpg
                        - queue_item_id: e85d14f1-98eb-462d-b3f0-4f7f78cc8c7c
                          track_id: 91d42a97-cb47-429e-b9e3-88fbff4e2680
                          queue_bucket: context
                          source_type: album
                          source_id: 4b28f3dd-2875-4811-aaf1-4fda7d3d113c
                          source_title: Late Night Drive
                          source_position: 2
                          added_at: '2026-04-18T20:00:19.000Z'
                          stream_url: https://cdn.rythmify.app/tracks/91d42a97-cb47-429e-b9e3-88fbff4e2680/stream.mp3
                          track_title: Runaway Pulse
                          artist_name: Echo Atlas
                          duration: 219
                          cover_image: https://cdn.rythmify.app/covers/example.jpg
                      saved_at: '2026-04-18T20:00:20.000Z'
                    message: Player state updated successfully.
                nextUpGenre:
                  summary: Next up items stay ahead of the old context bucket
                  value:
                    data:
                      track_id: 63f8f162-b255-4525-bf71-9913541cbbc5
                      track_title: Midnight City Lights
                      artist_name: DJ Nova
                      stream_url: https://cdn.rythmify.app/tracks/63f8f162-b255-4525-bf71-9913541cbbc5/stream.mp3
                      duration: 182
                      cover_image: https://cdn.rythmify.app/covers/example.jpg
                      position_seconds: 1473.8
                      volume: 0.49
                      queue:
                        - queue_item_id: 5ef3df1d-c7fe-4f59-a00a-7a987ac14fef
                          track_id: 39c7c3c3-7d02-4ac1-a647-a2fa0401de02
                          queue_bucket: next_up
                          source_type: genre
                          source_id: 6c6d6f9f-2e4a-4c0e-84e6-1738a29edb8d
                          source_title: Electronic
                          source_position: 1
                          added_at: '2026-04-18T20:00:18.294Z'
                          stream_url: https://cdn.rythmify.app/tracks/39c7c3c3-7d02-4ac1-a647-a2fa0401de02/stream.mp3
                          track_title: First Light
                          artist_name: Aurora Lane
                          duration: 201
                          cover_image: https://cdn.rythmify.app/covers/example.jpg
                        - queue_item_id: 7f9df8ad-bccf-4a06-a28b-f7db6354bb3d
                          track_id: 91d42a97-cb47-429e-b9e3-88fbff4e2680
                          queue_bucket: next_up
                          source_type: genre
                          source_id: 6c6d6f9f-2e4a-4c0e-84e6-1738a29edb8d
                          source_title: Electronic
                          source_position: 2
                          added_at: '2026-04-18T20:00:18.295Z'
                          stream_url: https://cdn.rythmify.app/tracks/91d42a97-cb47-429e-b9e3-88fbff4e2680/stream.mp3
                          track_title: Runaway Pulse
                          artist_name: Echo Atlas
                          duration: 219
                          cover_image: https://cdn.rythmify.app/covers/example.jpg
                        - queue_item_id: e85d14f1-98eb-462d-b3f0-4f7f78cc8c7c
                          track_id: 6d0b7921-cf0e-4fd2-9377-2c7a2dc8c402
                          queue_bucket: context
                          source_type: playlist
                          source_id: 4b28f3dd-2875-4811-aaf1-4fda7d3d113c
                          source_title: My Running Mix
                          source_position: 5
                          added_at: '2026-04-18T20:00:19.000Z'
                          stream_url: https://cdn.rythmify.app/tracks/6d0b7921-cf0e-4fd2-9377-2c7a2dc8c402/stream.mp3
                          track_title: Neon Horizon
                          artist_name: Atlas Bloom
                          duration: 205
                          cover_image: https://cdn.rythmify.app/covers/example.jpg
                      saved_at: '2026-04-18T20:00:20.000Z'
                    message: Player state updated successfully.
                repostsDefaultSelf:
                  summary: User-scoped contexts store the effective user id in source metadata
                  value:
                    data:
                      track_id: null
                      track_title: null
                      artist_name: null
                      stream_url: null
                      duration: null
                      cover_image: null
                      position_seconds: 0
                      volume: 1
                      queue:
                        - queue_item_id: e85d14f1-98eb-462d-b3f0-4f7f78cc8c7c
                          track_id: 91d42a97-cb47-429e-b9e3-88fbff4e2680
                          queue_bucket: next_up
                          source_type: reposts
                          source_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                          source_title: Your reposts
                          source_position: 1
                          added_at: '2026-04-18T20:00:19.000Z'
                          stream_url: https://cdn.rythmify.app/tracks/91d42a97-cb47-429e-b9e3-88fbff4e2680/stream.mp3
                          track_title: Runaway Pulse
                          artist_name: Echo Atlas
                          duration: 219
                          cover_image: https://cdn.rythmify.app/covers/example.jpg
                      saved_at: '2026-04-18T20:00:20.000Z'
                    message: Player state updated successfully.
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Context source not found, inaccessible, or empty after playable filtering, including when every resolved track is unavailable for playback in the request country.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                sourceMissing:
                  summary: Source does not exist
                  value:
                    error:
                      code: PLAYLIST_NOT_FOUND
                      message: Playlist not found.
                contextEmpty:
                  summary: Source resolved but yielded no playable tracks
                  value:
                    error:
                      code: QUEUE_CONTEXT_EMPTY
                      message: No playable tracks found for this context.
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /me/playback/sync:
    post:
      description: |
        Syncs offline/backfilled listening history and the latest reconnect player state
        for the authenticated user.

        History events reuse the existing listening-history dedupe rules.
        The incoming `current_state` only overwrites stored player state when
        `state_updated_at` is newer than the currently saved state.
        Requests accept legacy queue track UUID-formatted strings and rich queue-item objects.
        Responses always return normalized queue-item objects.
        Track URLs in returned player state may be null when region-restricted for `X-Country-Code`.
      tags: [Playback]
      summary: Sync offline playback history and current state
      operationId: syncPlayback
      parameters:
        - $ref: '#/components/parameters/XCountryCode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaybackSyncRequest'
            example:
              history_events:
                - track_id: 39c7c3c3-7d02-4ac1-a647-a2fa0401de02
                  played_at: '2026-04-18T19:45:00Z'
                  duration_played_seconds: 100
              current_state:
                track_id: 63f8f162-b255-4525-bf71-9913541cbbc5
                position_seconds: 1473.8
                volume: 0.49
                queue:
                  - track_id: 39c7c3c3-7d02-4ac1-a647-a2fa0401de02
                  - queue_item_id: e85d14f1-98eb-462d-b3f0-4f7f78cc8c7c
                    track_id: 91d42a97-cb47-429e-b9e3-88fbff4e2680
                    queue_bucket: context
                    source_type: playlist
                    source_id: 4b28f3dd-2875-4811-aaf1-4fda7d3d113c
                    source_title: My Running Mix
                    source_position: 5
                    added_at: '2026-04-18T20:00:19.000Z'
                state_updated_at: '2026-04-18T20:00:18.294Z'
      responses:
        '200':
          description: Offline playback sync completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaybackSyncResponse'
              example:
                data:
                  history_events_received: 1
                  history_events_recorded: 1
                  history_events_deduplicated: 0
                  current_state_saved: true
                  current_state_ignored_as_stale: false
                  current_state:
                    track_id: 63f8f162-b255-4525-bf71-9913541cbbc5
                    track_title: Midnight City Lights
                    artist_name: DJ Nova
                    stream_url: https://cdn.rythmify.app/tracks/63f8f162-b255-4525-bf71-9913541cbbc5/stream.mp3
                    duration: 182
                    cover_image: https://cdn.rythmify.app/covers/example.jpg
                    position_seconds: 1473.8
                    volume: 0.49
                    queue:
                      - queue_item_id: 5ef3df1d-c7fe-4f59-a00a-7a987ac14fef
                        track_id: 39c7c3c3-7d02-4ac1-a647-a2fa0401de02
                        queue_bucket: next_up
                        source_type: track
                        source_id: null
                        source_title: null
                        source_position: null
                        added_at: '2026-04-18T20:00:18.294Z'
                        stream_url: https://cdn.rythmify.app/tracks/39c7c3c3-7d02-4ac1-a647-a2fa0401de02/stream.mp3
                        track_title: First Light
                        artist_name: Aurora Lane
                        duration: 201
                        cover_image: https://cdn.rythmify.app/covers/example.jpg
                      - queue_item_id: e85d14f1-98eb-462d-b3f0-4f7f78cc8c7c
                        track_id: 91d42a97-cb47-429e-b9e3-88fbff4e2680
                        queue_bucket: context
                        source_type: playlist
                        source_id: 4b28f3dd-2875-4811-aaf1-4fda7d3d113c
                        source_title: My Running Mix
                        source_position: 5
                        added_at: '2026-04-18T20:00:19.000Z'
                        stream_url: https://cdn.rythmify.app/tracks/91d42a97-cb47-429e-b9e3-88fbff4e2680/stream.mp3
                        track_title: Runaway Pulse
                        artist_name: Echo Atlas
                        duration: 219
                        cover_image: https://cdn.rythmify.app/covers/example.jpg
                    saved_at: '2026-04-18T20:00:18.294Z'
                message: Playback sync completed successfully.
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Track not found or not accessible.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /me/history:
    get:
      description: Returns deduplicated recently played tracks ordered by newest last_played_at first. Cleared history rows are excluded. Playable URLs may be null when region-restricted for `X-Country-Code`.
      tags: [Playback]
      summary: Get recently played tracks (deduplicated, paginated)
      operationId: getRecentlyPlayed
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 20, minimum: 1, maximum: 100 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
        - $ref: '#/components/parameters/XCountryCode'
      responses:
        '200':
          description: Deduplicated recently played tracks returned with offset pagination metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecentlyPlayedResponse'
              example:
                data:
                  - track:
                      id: e5f6a7b8-c9d0-1234-efab-567890abcdef
                      title: Summer Vibes
                      genre: Electronic
                      duration: 213
                      cover_image: https://cdn.rythmify.com/covers/track1.jpg
                      user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      artist_name: DJ Karim
                      play_count: 4200
                      like_count: 312
                      comment_count: 47
                      repost_count: 19
                      stream_url: https://cdn.rythmify.com/tracks/e5f6a7b8/stream.mp3
                      audio_url: https://cdn.rythmify.com/tracks/e5f6a7b8/audio.mp3
                      tags: [house, summer, cairo]
                      is_liked_by_me: true
                      is_reposted_by_me: false
                      is_artist_followed_by_me: true
                    last_played_at: '2026-04-03T10:45:00Z'
                pagination:
                  limit: 20
                  offset: 0
                  total: 57
                message: Recently played fetched successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      description: Clears all active listening history for the authenticated user by marking rows with deleted_at. Rows are retained.
      tags: [Playback]
      summary: Clear listening history
      operationId: clearListeningHistory
      responses:
        '204':
          description: Listening history cleared. No response body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /me/listening-history:
    get:
      description: Returns the complete play-by-play listening history, paginated. Cleared history rows are excluded. Playable URLs may be null when region-restricted for `X-Country-Code`.
      tags: [Playback]
      summary: Full paginated listening history
      operationId: getListeningHistory
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 20, minimum: 1, maximum: 100 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
        - $ref: '#/components/parameters/XCountryCode'
      responses:
        '200':
          description: Paginated listening history returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListeningHistoryResponse'
              example:
                data:
                  - id: 9a8b7c6d-5e4f-4321-9abc-def012345678
                    track:
                      id: e5f6a7b8-c9d0-1234-efab-567890abcdef
                      title: Summer Vibes
                      genre: Electronic
                      duration: 213
                      cover_image: https://cdn.rythmify.com/covers/track1.jpg
                      user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      artist_name: DJ Karim
                      play_count: 4200
                      like_count: 312
                      comment_count: 47
                      repost_count: 19
                      stream_url: https://cdn.rythmify.com/tracks/e5f6a7b8/stream.mp3
                      audio_url: https://cdn.rythmify.com/tracks/e5f6a7b8/audio.mp3
                    played_at: '2026-04-03T10:45:00Z'
                pagination:
                  limit: 20
                  offset: 0
                  total: 1
                message: Listening history fetched successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  # ==========================================================
  # Module 7 — Sets & Playlists
  # ==========================================================
  # UNVERIFIED — no matching route found in src/routes/ as of audit date
  # getUserPlaylists handler exists in playlists.controller.js but is not mounted
  # in any route file. The GET /playlists endpoint (with ?mine&owner_user_id) covers this.
  /users/{user_id}/playlists:
    get:
      description: |
        Returns a paginated list of public playlists created by the specified user. 
        Only returns items where subtype is 'playlist' and is_public is true.

        Access rules:
        - If the requested user's profile is private, non-followers receive a 403 Forbidden.
      tags: [Playlists]
      summary: Get a user's public playlists
      operationId: getUserPlaylists
      security: []
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated list of public playlists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistListResponse'
        '403':
          description: Profile is private and requester does not have access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'

  # UNVERIFIED — no matching route found in src/routes/ as of audit date
  # getUserAlbums handler exists in playlists.controller.js but is not mounted
  # in any route file. The GET /playlists endpoint (with ?is_album_view=true) covers this.
  /users/{user_id}/albums:
    get:
      description: |
        Returns a paginated list of public albums created by the specified user.
        Only returns items where is_album_view is true (or subtype is 'album'/'ep'/'single') and is_public is true.

        Access rules:
        - If the requested user's profile is private, non-followers receive a 403 Forbidden.
      tags: [Playlists]
      summary: Get a user's public albums
      operationId: getUserAlbums
      security: []
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated list of public albums.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistListResponse'
        '403':
          description: Profile is private and requester does not have access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /playlists:
    post:
      tags: [Playlists]
      summary: Create a playlist
      description: |
        Creates a new playlist (set) for the authenticated user.

        Notes:
        - If `is_public=false`, the playlist is treated as "secret/private" (shareable by token/link).
        - Free users may create up to 2 playlists.
        - Premium users have unlimited playlists.
        - If the user's effective plan does not allow more playlists, this endpoint returns 403 with code `SUBSCRIPTION_LIMIT_REACHED`.
      operationId: createPlaylist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePlaylistRequest'

      responses:
        '201':
          description: Playlist created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistResponse'
              example:
                data:
                  playlist_id: 8d5a8f6c-7b4a-4c7a-9c25-9a9f1e3a12aa
                  owner_user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  name: 'Gym Mix'
                  slug: 'gym-mix'
                  description: 'High energy tracks'
                  is_public: true
                  cover_image: 'https://cdn.rythmify.com/playlists/8d5a8f6c-7b4a-4c7a-9c25-9a9f1e3a12aa/cover.jpg'
                  subtype: 'playlist'
                  release_date: '2026-03-06'
                  genre_id: 6c6d6f9f-2e4a-4c0e-84e6-1738a29edb8d
                  track_count: 0
                  like_count: 0
                  repost_count: 0
                  created_at: '2026-03-06T10:00:00Z'
                  updated_at: '2026-03-06T10:00:00Z'
                message: 'Playlist created successfully.'

        '400':
          $ref: '#/components/responses/ValidationError'

        '401':
          $ref: '#/components/responses/Unauthorized'

        '403':
          description: Free plan playlist limit reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: SUBSCRIPTION_LIMIT_REACHED
                  message: Free plan playlist limit reached. Upgrade to premium for unlimited playlists.

        '422':
          description: Business rule violation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: BUSINESS_LIMIT_REACHED
                  message: Playlist limit reached for your current plan.

        '429':
          $ref: '#/components/responses/RateLimited'

    get:
      tags: [Playlists]
      summary: List playlists
      description: |
        Returns a paginated list of playlists.

        By default, this returns **public** playlists.

        To list the authenticated user's library, set `mine=true` and include Bearer auth.

        Filters:
        - `filter=created|liked` applies only when `mine=true`.
        - `is_album_view=true` returns non-regular playlists (all subtypes except `playlist`).
        - `subtype` filters by one subtype when `is_album_view` is not used.
      operationId: listPlaylists
      security: [] # public by default; auth required only when mine=true

      parameters:
        - name: mine
          in: query
          required: false
          description: If true, returns the authenticated user's playlists (public + private).
          schema:
            type: boolean
            default: false

        - name: filter
          in: query
          required: false
          description: Library filter for authenticated requests (`mine=true`). Defaults to `created` when omitted.
          schema:
            type: string
            enum: [created, liked]
            default: created

        - name: q
          in: query
          required: false
          description: Search by playlist name (simple contains match).
          schema:
            type: string
            maxLength: 100

        - name: subtype
          in: query
          required: false
          description: Filter by playlist subtype. Ignored when `is_album_view=true`.
          schema:
            type: string
            enum: [playlist, album, ep, single, compilation]

        - name: is_album_view
          in: query
          required: false
          description: If true, returns all non-playlist subtypes (album/ep/single/compilation).
          schema:
            type: boolean
            default: false

        - name: limit
          in: query
          required: false
          description: Page size (server-clamped to 1..50).
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20

        - name: offset
          in: query
          required: false
          description: Pagination offset.
          schema:
            type: integer
            minimum: 0
            default: 0

      responses:
        '200':
          description: Playlists returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistListResponse'

        '400':
          $ref: '#/components/responses/ValidationError'

        '401':
          $ref: '#/components/responses/Unauthorized'

        '429':
          $ref: '#/components/responses/RateLimited'

  /playlists/{playlist_id}:
    get:
      tags: [Playlists]
      summary: Get playlist details
      description: |
        Returns playlist metadata and its tracks in order.

        `cover_image` is always included in the response.
        If no custom playlist cover exists, the backend may fall back to the first track cover.

        Access rules:
        - Public playlists: accessible to anyone.
        - Private (secret) playlists: accessible if either:
          1) the requester is the owner (via Bearer token), OR
          2) `secret_token` is provided.

        Response note:
        - `secret_token` is returned only when the requester is the playlist owner.
        - For non-owners, `secret_token` is omitted from the response.
        - For private playlists accessed via query token, the token is used for authorization only and is not returned for non-owners.
      operationId: getPlaylistById
      security: [] # public endpoint (Authorization header may still be sent optionally)

      parameters:
        - name: playlist_id
          in: path
          required: true
          description: Playlist ID.
          schema:
            type: string
            format: uuid

        - name: secret_token
          in: query
          required: false
          description: Required only to access private/secret playlists when not authenticated as the owner.
          schema:
            type: string

        - name: include_tracks
          in: query
          required: false
          description: If false, returns only playlist metadata (without tracks array). If true, `tracks` is included.
          schema:
            type: boolean
            default: true

      responses:
        '200':
          description: Playlist returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistGetResponse'
              example:
                data:
                  playlist_id: 8d5a8f6c-7b4a-4c7a-9c25-9a9f1e3a12aa
                  owner_user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  name: 'Gym Mix'
                  slug: 'gym-mix'
                  description: 'High energy tracks'
                  is_public: true
                  cover_image: 'https://cdn.rythmify.com/playlists/8d5a8f6c-7b4a-4c7a-9c25-9a9f1e3a12aa/cover.jpg'
                  subtype: 'playlist'
                  track_count: 2
                  like_count: 15
                  repost_count: 1
                  created_at: '2026-03-06T10:00:00Z'
                  updated_at: '2026-03-06T10:30:00Z'
                  tracks:
                    - track_id: e5f6a7b8-c9d0-1234-efab-567890abcdef
                      position: 1
                      added_at: '2026-03-06T10:01:00Z'
                    - track_id: 11111111-c9d0-1234-efab-567890abcdef
                      position: 2
                      added_at: '2026-03-06T10:03:00Z'
                message: Playlist details fetched successfully.

        '401':
          $ref: '#/components/responses/Unauthorized'

        '403':
          description: Not allowed to access this playlist (private and missing permission/token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: PRIVATE_PLAYLIST_ACCESS_DENIED
                  message: This playlist is private.

        '404':
          description: Playlist not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: PLAYLIST_NOT_FOUND
                  message: Playlist not found.

        '429':
          $ref: '#/components/responses/RateLimited'

    patch:
      tags: [Playlists]
      summary: Update playlist
      description: |
        Updates playlist metadata for the authenticated owner.

        Editable fields:
        - `name`
        - `description`
        - `is_public`
        - `cover_image`
        - `subtype`
        - `slug`
        - `release_date`
        - `genre_id`
        - `tags`

        Notes:
        - Only the playlist owner can update a playlist.
        - If `is_public=false`, the playlist becomes secret/private and gets a secret token if missing.
        - If `is_public=true`, any existing secret token is preserved (not cleared).
        - For `subtype` values `album`, `ep`, `single`, or `compilation`, `release_date` is required (either already stored or provided in this request).
        - Send `genre_id` as `null` (or empty form value) to clear the existing genre.
        - When `tags` is provided, existing playlist tags are replaced.
        - If no custom playlist cover exists after update, response `cover_image` falls back to the first track cover (if available).
        - To remove an uploaded cover, send `remove_cover_image=true` (or `cover_image` as an empty form value).
      operationId: updatePlaylist
      parameters:
        - name: playlist_id
          in: path
          required: true
          description: Playlist ID.
          schema:
            type: string
            format: uuid

      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UpdatePlaylistRequest'

      responses:
        '200':
          description: Playlist updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistResponse'
              example:
                data:
                  playlist_id: 8d5a8f6c-7b4a-4c7a-9c25-9a9f1e3a12aa
                  owner_user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  name: 'Updated Gym Mix'
                  slug: 'updated-gym-mix'
                  description: 'Updated high energy tracks'
                  cover_image: 'https://cdn.rythmify.com/playlists/8d5a8f6c-7b4a-4c7a-9c25-9a9f1e3a12aa/cover.jpg'
                  subtype: 'album'
                  is_public: false
                  release_date: '2026-03-06'
                  genre_id: 6c6d6f9f-2e4a-4c0e-84e6-1738a29edb8d
                  tags:
                    - id: 1a2b3c4d-5e6f-47a8-90ab-cdef12345678
                      name: workout
                    - id: 2b3c4d5e-6f70-48a9-90bc-def123456789
                      name: edm
                  track_count: 12
                  like_count: 340
                  repost_count: 10
                  created_at: '2026-03-06T10:00:00Z'
                  updated_at: '2026-03-06T11:00:00Z'
                message: Playlist updated successfully.

        '400':
          $ref: '#/components/responses/ValidationError'

        '401':
          $ref: '#/components/responses/Unauthorized'

        '403':
          description: Only the playlist owner can update this playlist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: PLAYLIST_FORBIDDEN
                  message: You are not allowed to update this playlist.

        '404':
          description: Playlist not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: PLAYLIST_NOT_FOUND
                  message: Playlist not found.

        '422':
          description: Business rule violation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: BUSINESS_RULE_VIOLATION
                  message: At least one updatable field must be provided.

        '429':
          $ref: '#/components/responses/RateLimited'

    delete:
      tags: [Playlists]
      summary: Delete playlist
      description: |
        Deletes a playlist owned by the authenticated user.

        Notes:
        - Only the playlist owner can delete a playlist.
        - Deleting a playlist also removes its playlist_tracks entries.
      operationId: deletePlaylist
      parameters:
        - name: playlist_id
          in: path
          required: true
          description: Playlist ID.
          schema:
            type: string
            format: uuid

      responses:
        '200':
          description: Playlist deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
              example:
                data:
                  success: true
                message: Playlist deleted successfully.

        '401':
          $ref: '#/components/responses/Unauthorized'

        '403':
          description: Only the playlist owner can delete this playlist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: PLAYLIST_FORBIDDEN
                  message: You are not allowed to delete this playlist.

        '404':
          description: Playlist not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: PLAYLIST_NOT_FOUND
                  message: Playlist not found.

        '429':
          $ref: '#/components/responses/RateLimited'

  /playlists/{playlist_id}/tracks:
    get:
      tags: [Playlists]
      summary: Get playlist tracks (paginated)
      description: |
        Returns paginated tracks for a playlist.

        Access rules:
        - Public playlists: accessible to anyone.
        - Private playlists: accessible if either:
          1) the requester is the owner (via Bearer token), OR
          2) a valid `secret_token` query parameter is provided.

        Pagination behavior:
        - `page` is 1-based and clamped to a minimum of 1.
        - `limit` defaults to 20 and is clamped to a maximum of 100.
      operationId: getPlaylistTracks
      security: []

      parameters:
        - name: playlist_id
          in: path
          required: true
          description: Playlist ID.
          schema:
            type: string
            format: uuid

        - name: secret_token
          in: query
          required: false
          description: Required only to access private playlists when not authenticated as the owner.
          schema:
            type: string

        - name: page
          in: query
          required: false
          description: Page number (1-based).
          schema:
            type: integer
            minimum: 1
            default: 1

        - name: limit
          in: query
          required: false
          description: Number of tracks per page (server-clamped to max 100).
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20

      responses:
        '200':
          description: Playlist tracks returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistTracksGetResponse'
              example:
                data:
                  playlist_id: 8d5a8f6c-7b4a-4c7a-9c25-9a9f1e3a12aa
                  tracks:
                    - track_id: e5f6a7b8-c9d0-1234-efab-567890abcdef
                      position: 1
                      added_at: '2026-03-06T10:01:00Z'
                      title: Lift Me Up
                      duration: 214
                      cover_image: 'https://cdn.rythmify.com/tracks/e5f6a7b8/cover.jpg'
                      is_public: true
                      deleted_at: null
                      artist_name: DJ Nova
                      artist_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  pagination:
                    page: 1
                    per_page: 20
                    total_items: 84
                    total_pages: 5
                    has_next: true
                    has_prev: false
                message: Playlist tracks fetched successfully.

        '403':
          description: Access denied for private playlist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: PLAYLIST_ACCESS_DENIED
                  message: You do not have access to this playlist.

        '404':
          description: Playlist not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: PLAYLIST_NOT_FOUND
                  message: Playlist not found.

        '429':
          $ref: '#/components/responses/RateLimited'

    post:
      tags: [Playlists]
      summary: Add track to playlist
      description: |
        Adds a track to a playlist owned by the authenticated user.

        Ordering rules:
        - If `position` is provided, the track is inserted at that position and existing tracks
          at/after that position shift down.
        - If `position` is not provided, the track is appended to the end.

        Notes:
        - A track cannot appear twice in the same playlist.
        - Only the playlist owner can add tracks.
      operationId: addTrackToPlaylist
      parameters:
        - name: playlist_id
          in: path
          required: true
          description: Playlist ID.
          schema:
            type: string
            format: uuid

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddTrackToPlaylistRequest'

      responses:
        '201':
          description: Track added successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistGetResponse'
              example:
                data:
                  playlist_id: 8d5a8f6c-7b4a-4c7a-9c25-9a9f1e3a12aa
                  owner_user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  name: 'Gym Mix'
                  description: 'High energy tracks'
                  is_public: true
                  created_at: '2026-03-06T10:00:00Z'
                  track_count: 3
                  like_count: 0
                  tracks:
                    - track_id: e5f6a7b8-c9d0-1234-efab-567890abcdef
                      position: 1
                      added_at: '2026-03-06T10:01:00Z'
                    - track_id: 11111111-2222-3333-4444-555555555555
                      position: 2
                      added_at: '2026-03-06T10:02:00Z'
                    - track_id: 99999999-aaaa-bbbb-cccc-dddddddddddd
                      position: 3
                      added_at: '2026-03-06T10:03:00Z'
                message: Track added to playlist successfully.

        '400':
          $ref: '#/components/responses/ValidationError'

        '401':
          $ref: '#/components/responses/Unauthorized'

        '403':
          description: Only the playlist owner can modify this playlist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: PLAYLIST_FORBIDDEN
                  message: You are not allowed to modify this playlist.

        '404':
          description: Playlist or track not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                playlistNotFound:
                  value:
                    error:
                      code: PLAYLIST_NOT_FOUND
                      message: Playlist not found.
                trackNotFound:
                  value:
                    error:
                      code: TRACK_NOT_FOUND
                      message: Track not found.

        '409':
          description: Track already exists in the playlist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: PLAYLIST_TRACK_ALREADY_EXISTS
                  message: Track already exists in this playlist.

        '422':
          description: Business rule violation (invalid position).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: PLAYLIST_POSITION_INVALID
                  message: Position must be between 1 and the next available position.

        '429':
          $ref: '#/components/responses/RateLimited'

  /playlists/{playlist_id}/tracks/reorder:
    patch:
      tags: [Playlists]
      summary: Reorder tracks in playlist
      description: |
        Reorders tracks inside a playlist owned by the authenticated user.

        Rules:
        - Provide the full ordered list of tracks with their new `position` values (1-based).
        - Positions must be unique and start at 1 with no gaps.
        - All track_ids must already exist in the playlist.
      operationId: reorderPlaylistTracks
      parameters:
        - name: playlist_id
          in: path
          required: true
          description: Playlist ID.
          schema:
            type: string
            format: uuid

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReorderPlaylistTracksRequest'

      responses:
        '200':
          description: Playlist tracks reordered successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistGetResponse'
              example:
                data:
                  playlist_id: 8d5a8f6c-7b4a-4c7a-9c25-9a9f1e3a12aa
                  owner_user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  name: 'Gym Mix'
                  description: 'High energy tracks'
                  is_public: true
                  created_at: '2026-03-06T10:00:00Z'
                  track_count: 3
                  like_count: 0
                  tracks:
                    - track_id: 99999999-aaaa-bbbb-cccc-dddddddddddd
                      position: 1
                      added_at: '2026-03-06T10:03:00Z'
                    - track_id: e5f6a7b8-c9d0-1234-efab-567890abcdef
                      position: 2
                      added_at: '2026-03-06T10:01:00Z'
                    - track_id: 11111111-2222-3333-4444-555555555555
                      position: 3
                      added_at: '2026-03-06T10:02:00Z'
                message: Playlist tracks reordered successfully.

        '400':
          $ref: '#/components/responses/ValidationError'

        '401':
          $ref: '#/components/responses/Unauthorized'

        '403':
          description: Only the playlist owner can modify this playlist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: PLAYLIST_FORBIDDEN
                  message: You are not allowed to modify this playlist.

        '404':
          description: Playlist not found (or track not found in playlist).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                playlistNotFound:
                  value:
                    error:
                      code: PLAYLIST_NOT_FOUND
                      message: Playlist not found.
                trackNotInPlaylist:
                  value:
                    error:
                      code: PLAYLIST_TRACK_NOT_FOUND
                      message: One or more tracks are not in this playlist.

        '422':
          description: Business rule violation (bad positions).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                positionsInvalid:
                  value:
                    error:
                      code: PLAYLIST_POSITIONS_INVALID
                      message: Positions must start at 1 with no gaps and be unique.
                notFullList:
                  value:
                    error:
                      code: PLAYLIST_REORDER_REQUIRES_FULL_LIST
                      message: Reorder requires a full list of playlist tracks.

        '429':
          $ref: '#/components/responses/RateLimited'

  /playlists/{playlist_id}/tracks/{track_id}:
    delete:
      tags: [Playlists]
      summary: Remove track from playlist
      description: |
        Removes a track from a playlist owned by the authenticated user.

        Notes:
        - Only the playlist owner can remove tracks.
        - After removal, the server should re-normalize positions so they remain 1..N with no gaps.
      operationId: removeTrackFromPlaylist
      parameters:
        - name: playlist_id
          in: path
          required: true
          description: Playlist ID.
          schema:
            type: string
            format: uuid

        - name: track_id
          in: path
          required: true
          description: Track ID to remove.
          schema:
            type: string
            format: uuid

      responses:
        '200':
          description: Track removed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistGetResponse'
              example:
                data:
                  playlist_id: 8d5a8f6c-7b4a-4c7a-9c25-9a9f1e3a12aa
                  owner_user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  name: 'Gym Mix'
                  description: 'High energy tracks'
                  is_public: true
                  created_at: '2026-03-06T10:00:00Z'
                  track_count: 2
                  like_count: 0
                  tracks:
                    - track_id: e5f6a7b8-c9d0-1234-efab-567890abcdef
                      position: 1
                      added_at: '2026-03-06T10:01:00Z'
                    - track_id: 11111111-2222-3333-4444-555555555555
                      position: 2
                      added_at: '2026-03-06T10:02:00Z'
                message: Track removed from playlist successfully.

        '400':
          $ref: '#/components/responses/ValidationError'

        '401':
          $ref: '#/components/responses/Unauthorized'

        '403':
          description: Only the playlist owner can modify this playlist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: PLAYLIST_FORBIDDEN
                  message: You are not allowed to modify this playlist.

        '404':
          description: Playlist not found or track not in playlist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                playlistNotFound:
                  value:
                    error:
                      code: PLAYLIST_NOT_FOUND
                      message: Playlist not found.
                trackNotInPlaylist:
                  value:
                    error:
                      code: PLAYLIST_TRACK_NOT_FOUND
                      message: Track not found in this playlist.

        '429':
          $ref: '#/components/responses/RateLimited'

  /playlists/{playlist_id}/embed:
    get:
      tags: [Playlists]
      summary: Generate playlist embed code
      description: |
        Generates an embeddable iframe snippet for a playlist.

        Access rules:
        - Public playlists: accessible to anyone.
        - Private playlists: require `secret_token` unless the requester is the owner.

        The returned iframe can be used on external websites to embed the playlist player.
      operationId: getPlaylistEmbed
      security: [] # public

      parameters:
        - name: playlist_id
          in: path
          required: true
          description: Playlist ID.
          schema:
            type: string
            format: uuid

        - name: secret_token
          in: query
          required: false
          description: Secret token required for private playlists.
          schema:
            type: string

        - name: theme
          in: query
          required: false
          description: Player theme.
          schema:
            type: string
            enum: [light, dark]
            default: light

        - name: autoplay
          in: query
          required: false
          description: Whether the embedded player should autoplay.
          schema:
            type: boolean
            default: false

        - name: width
          in: query
          required: false
          description: Width of the iframe player.
          schema:
            type: integer
            minimum: 200
            maximum: 1200
            default: 600

        - name: height
          in: query
          required: false
          description: Height of the iframe player.
          schema:
            type: integer
            minimum: 100
            maximum: 600
            default: 200

      responses:
        '200':
          description: Embed code generated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistEmbedResponse'
              example:
                data:
                  embed_url: https://api.rythmify.com/embed/playlists/8d5a8f6c-7b4a-4c7a-9c25-9a9f1e3a12aa
                  iframe_html: "<iframe src='https://api.rythmify.com/embed/playlists/8d5a8f6c-7b4a-4c7a-9c25-9a9f1e3a12aa' width='600' height='200' frameborder='0'></iframe>"
                message: Playlist embed code generated successfully.

        '404':
          description: Playlist not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: PLAYLIST_NOT_FOUND
                  message: Playlist not found.

        '403':
          description: Playlist is private and no valid secret token was provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: PLAYLIST_ACCESS_DENIED
                  message: Private playlist requires a valid secret token.

        '429':
          $ref: '#/components/responses/RateLimited'

  /playlists/{playlist_id}/radio-tracks:
    get:
      tags: [Track Discovery, Playlists]
      summary: Get the tracks for a saved track radio
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PlaylistId'
        - name: limit
          in: query
          schema: { type: integer, default: 20 }
        - name: offset
          in: query
          schema: { type: integer, default: 0 }
      responses:
        '200':
          description: Successfully fetched tracks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackRadioTracksResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /playlists/{playlist_id}/convert:
    post:
      description: Snapshot a generated playlist into a real regular playlist.
      tags: [Playlists]
      summary: Convert a generated playlist
      operationId: convertPlaylist
      parameters:
        - name: playlist_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                is_public:
                  type: boolean
      responses:
        '201':
          description: Playlist converted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Forbidden or not generated playlist.
        '404':
          $ref: '#/components/responses/NotFound'

  /stations/{artist_id}/like:
    post:
      description: Saves an artist station to user library.
      tags: [Stations]
      summary: Save an artist station
      operationId: likeStation
      parameters:
        - name: artist_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Station saved.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      description: Removes an artist station from user library.
      tags: [Stations]
      summary: Unsave an artist station
      operationId: unlikeStation
      parameters:
        - name: artist_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Station removed.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  # ==========================================================
  # Module 7.5 — Home & Discovery + Genre Discovery
  # ==========================================================

  /home:
    get:
      tags: [Home & Discovery]
      summary: Get full home page
      operationId: getHome
      description: |
        Returns all home page sections in one response.
        All sub-queries run in parallel on the server.

        Sections returned:
        - `curated` — guest discovery mix previews (multi-genre, preview-only)
        - `hot_for_you` — one featured track of the day
        - `trending_by_genre` — genre tab bar + first tab pre-loaded
        - `more_of_what_you_like` — tracks from liked genres and followed artists (null for guests)
        - `albums_for_you` — album recommendations with first-track preview (null for guests)
        - `mixed_for_you` — up to 6 auto-generated genre mixes (null for guests)
        - `made_for_you` — Daily Drops + Weekly Wave summaries (null for guests)
        - `artists_to_watch` — emerging artists by play velocity
        - `discover_with_stations` — artist-based radio stations

        Cross-section deduplication is applied server-side.
        Priority: hot_for_you → trending → more_of_what_you_like → mixed_for_you.
        Empty sections return `[]`, never `null`.
        Unauthenticated users receive global discovery sections and curated mix previews.
        `more_of_what_you_like`, `albums_for_you`, `mixed_for_you`, and `made_for_you` are null for guests.

        Curated mixes are generated dynamically from top-performing genres,
        combined into multi-genre previews, filtered for artist diversity,
        and include controlled randomness.

        Curated mixes are cached and refreshed periodically, so results can vary over time.
        Curated preview mix IDs (`mix_custom_<genreId1>_<genreId2>`) are frontend discovery IDs.
        They are not directly tied to the `/home/mixes/{mixId}` endpoint.
      security: []
      responses:
        '200':
          description: Home page data returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HomeResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /home/trending-by-genre/{genre_id}:
    get:
      description: Returns trending tracks for a single genre tab via lazy load.
      tags: [Home & Discovery]
      summary: Lazy-load trending tracks for a genre tab
      operationId: getTrendingByGenre
      security: []
      parameters:
        - name: genre_id
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: limit
          in: query
          schema: { type: integer, default: 20, minimum: 1, maximum: 50 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
      responses:
        '200':
          description: Trending tracks for this genre tab.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrendingByGenreTabResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'

  /home/hot-for-you:
    get:
      description: Returns the single featured track of the day, cached until midnight UTC.
      tags: [Home & Discovery]
      summary: Get the featured track of the day
      operationId: getHotForYou
      security: []
      responses:
        '200':
          description: Hot track returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotForYouResponse'
        '429':
          $ref: '#/components/responses/RateLimited'

  /home/more-of-what-you-like:
    get:
      description: Returns a paginated stream of tracks matching the user's genre and artist preferences.
      tags: [Home & Discovery]
      summary: Get tracks based on liked genres and followed artists
      operationId: getMoreOfWhatYouLike
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 20, minimum: 1, maximum: 50 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
      responses:
        '200':
          description: Tracks returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MoreOfWhatYouLikeResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /home/mixes/{mixId}:
    get:
      description: |
        Returns full details for a single mix.
        `mixId` may be either:
        - a persisted generated-playlist UUID for a saved mix
        - a synthetic discovery ID in the format `mix_genre_<genre_uuid>`
      tags: [Home & Discovery]
      summary: Get one mix with full tracks
      operationId: getMixById
      parameters:
        - name: mixId
          in: path
          required: true
          schema:
            type: string
          description: Persisted mix UUID or synthetic `mix_genre_<genre_uuid>` identifier.
          example: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '200':
          description: Mix returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MixDetailsResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /home/mixes/{mixId}/like:
    post:
      description: Likes a persisted authenticated mix. Mix IDs must be real playlist UUIDs; guest synthetic mix IDs are not valid here.
      tags: [Home & Discovery]
      summary: Like a persisted mix
      operationId: likeMix
      parameters:
        - name: mixId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '200':
          description: Mix was already liked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MixLikeResponse'
        '201':
          description: Mix liked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MixLikeResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'

    delete:
      description: Unlikes a persisted authenticated mix.
      tags: [Home & Discovery]
      summary: Unlike a persisted mix
      operationId: unlikeMix
      parameters:
        - name: mixId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '200':
          description: Mix unliked.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /home/made-for-you/daily:
    get:
      summary: Get Daily Drops mix
      description: Returns full tracks for the daily curated mix
      tags: [Home & Discovery]
      operationId: getDailyMix
      responses:
        '200':
          description: Daily mix returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MixDetailsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /home/made-for-you/weekly:
    get:
      summary: Get Weekly Wave mix
      description: Returns full tracks for the weekly curated mix
      tags: [Home & Discovery]
      operationId: getWeeklyMix
      responses:
        '200':
          description: Weekly mix returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MixDetailsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /home/stations:
    get:
      description: Returns artist-based radio stations ordered by follower count.
      tags: [Home & Discovery]
      summary: List artist radio stations
      operationId: listStations
      security: []
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 10, minimum: 1, maximum: 20 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
      responses:
        '200':
          description: Station list returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StationListResponse'
        '429':
          $ref: '#/components/responses/RateLimited'

  /home/stations/{artist_id}/tracks:
    get:
      description: Returns the track list for a specific artist radio station.
      tags: [Home & Discovery]
      summary: Get tracks for an artist station
      operationId: getStationTracks
      security: []
      parameters:
        - name: artist_id
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: limit
          in: query
          schema: { type: integer, default: 50, minimum: 1, maximum: 100 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
      responses:
        '200':
          description: Station tracks returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StationTracksResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'

  /home/albums-for-you:
    get:
      description: Returns album recommendations from followed artists or global top albums.
      tags: [Home & Discovery]
      summary: Get album recommendations
      operationId: getAlbumsForYou
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 10, minimum: 1, maximum: 20 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
      responses:
        '200':
          description: Albums returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlbumsForYouResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /home/artists-to-watch:
    get:
      description: Returns emerging artists ranked by plays-per-day over the last 90 days.
      tags: [Home & Discovery]
      summary: Get emerging artists by play velocity
      operationId: getArtistsToWatch
      security: []
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 10, minimum: 1, maximum: 20 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
      responses:
        '200':
          description: Emerging artists returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistsToWatchResponse'
        '429':
          $ref: '#/components/responses/RateLimited'

  /genres/{genre_id}/page:
    get:
      description: Returns all aggregated sections for a genre page in a single request.
      tags: [Genre Discovery]
      summary: Get full genre page
      operationId: getGenrePage
      security: []
      parameters:
        - name: genre_id
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: tracks_limit
          in: query
          schema: { type: integer, default: 20, minimum: 1, maximum: 50 }
        - name: artists_limit
          in: query
          schema: { type: integer, default: 10, minimum: 1, maximum: 20 }
        - name: playlists_limit
          in: query
          schema: { type: integer, default: 12, minimum: 1, maximum: 20 }
        - name: albums_limit
          in: query
          schema: { type: integer, default: 12, minimum: 1, maximum: 20 }
      responses:
        '200':
          description: Genre page data returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenrePageResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /genres/{genre_id}/tracks:
    get:
      description: Returns paginated tracks for the specified genre.
      tags: [Genre Discovery]
      summary: List tracks in a genre
      operationId: getGenreTracks
      security: []
      parameters:
        - name: genre_id
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: limit
          in: query
          schema: { type: integer, default: 20, minimum: 1, maximum: 50 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
        - name: sort
          in: query
          schema: { type: string, enum: [newest, popular], default: newest }
      responses:
        '200':
          description: Tracks returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenreTracksResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'

  /genres/{genre_id}/albums:
    get:
      description: Returns paginated albums for the specified genre.
      tags: [Genre Discovery]
      summary: List albums in a genre
      operationId: getGenreAlbums
      security: []
      parameters:
        - name: genre_id
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: limit
          in: query
          schema: { type: integer, default: 12, minimum: 1, maximum: 20 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
      responses:
        '200':
          description: Albums returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenreAlbumsResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'

  /genres/{genre_id}/playlists:
    get:
      description: Returns paginated playlists tagged or inferred for the specified genre.
      tags: [Genre Discovery]
      summary: List playlists in a genre
      operationId: getGenrePlaylists
      security: []
      parameters:
        - name: genre_id
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: limit
          in: query
          schema: { type: integer, default: 12, minimum: 1, maximum: 20 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
      responses:
        '200':
          description: Playlists returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenrePlaylistsResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'

  /genres/{genre_id}/artists:
    get:
      description: Returns top artists with at least one public track in the specified genre.
      tags: [Genre Discovery]
      summary: List top artists in a genre
      operationId: getGenreArtists
      security: []
      parameters:
        - name: genre_id
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: limit
          in: query
          schema: { type: integer, default: 10, minimum: 1, maximum: 20 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
      responses:
        '200':
          description: Artists returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenreArtistsResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'

  /genres/{genre_id}/like:
    post:
      description: Likes/saves a trending genre to library.
      tags: [Genre Discovery]
      summary: Like a trending genre
      operationId: likeGenreTrending
      parameters:
        - name: genre_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Genre trending saved.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      description: Unlikes/unsaves a trending genre from library.
      tags: [Genre Discovery]
      summary: Unlike a trending genre
      operationId: unlikeGenreTrending
      parameters:
        - name: genre_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Genre trending removed.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /tracks/{track_id}/like-radio:
    post:
      tags: [Track Discovery]
      summary: Save a track radio to your library
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/TrackId'
      responses:
        '201':
          description: Track radio saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackRadioLikeResponse'
    delete:
      tags: [Track Discovery]
      summary: Remove a track radio from your library
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/TrackId'
      responses:
        '200':
          description: Track radio removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnlikeResponse'

  /tracks/{track_id}/related:
    get:
      description: Returns tracks related by same artist and same genre, deduplicated.
      tags: [Track Discovery]
      summary: Get tracks related to a specific track
      operationId: getRelatedTracks
      security: []
      parameters:
        - $ref: '#/components/parameters/TrackId'
        - name: limit
          in: query
          schema: { type: integer, default: 20, minimum: 1, maximum: 50 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
      responses:
        '200':
          description: Related tracks returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelatedTracksResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  # ==========================================================
  # Module 8 — Feed, Search & Discovery
  # [FIX-1] Replaced single /feed with /feed (Following tab) + /feed/discover
  # [FIX-3] FeedItem schema replaces FeedTrack in feed responses
  # [FIX-6] Pagination changed to ListMeta (offset-based)
  # ==========================================================

  /feed:
    get:
      tags: [Feed]
      summary: Following tab — chronological feed from followed accounts
      description: |
        Returns a chronological stream of tracks and reposts from users
        the authenticated user follows. Each item is typed as either
        `track` (original upload) or `repost` (a repost by a followed user).

        When `item_type = "repost"`, the `repost_by` field contains the
        user who reposted it. The track data is always the original track.

        Only public, non-hidden, ready tracks are included.
        Admin-hidden tracks are excluded.
      operationId: getFollowingFeed
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 20, minimum: 1, maximum: 100 }
          description: Maximum number of items to return.
        - name: cursor
          in: query
          schema: { type: string }
          description: Opaque cursor for pagination. Pass the `nextCursor` value from the previous response to fetch the next page.
      responses:
        '200':
          description: Following feed returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorFeedResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  # Feed discovery tab — matches GET /feed/discovery in feed.routes.js
  /feed/discovery:
    get:
      tags: [Feed]
      summary: Discover tab — personalised recommended content stream
      description: |
        Returns a stream of recommended tracks based on the authenticated user's
        listening history, followed artists, and genre preferences.

        Unlike `GET /home` which returns structured sections, this endpoint
        returns a flat, cursor-paginated stream suitable for infinite scroll.

        Only public, non-hidden, ready tracks are included. Authentication is required.
      operationId: getDiscoverFeed
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 20, minimum: 1, maximum: 100 }
          description: Maximum number of items to return.
        - name: cursor
          in: query
          schema: { type: string }
          description: Opaque cursor for pagination. Pass the `nextCursor` value from the previous response.
      responses:
        '200':
          description: Discovery feed returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorFeedResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  # UNVERIFIED — no matching route found in src/routes/ as of audit date
  # /feed/trending does not exist in feed.routes.js. Only /feed and /feed/discovery are defined.
  /feed/trending:
    get:
      tags: [Feed]
      summary: Get trending tracks
      description: |
        Returns tracks ranked by recent play count and engagement velocity.
        Each result includes `rank` and `trend_score`.
      operationId: getTrendingFeed
      security: []
      parameters:
        - name: genre
          in: query
          schema: { type: string }
        - name: period
          in: query
          schema: { type: string, enum: [day, week, month], default: week }
        - name: limit
          in: query
          schema: { type: integer, default: 20, minimum: 1, maximum: 100 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
      responses:
        '200':
          description: Trending tracks returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrendingFeedResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'

  # [FIX-6][FIX-7] Search: pagination inside data, per-type meta
  /search:
    get:
      tags: [Search]
      summary: Global search
      operationId: search
      description: |
        Search across tracks, users, playlists, and albums using keyword matching.

        **type=everything** returns a blended feed of all resource types combined.
        Only `relevance` and `newest` sorts are supported for `type=everything`.

        For all other types (`tracks`, `users`, `playlists`, `albums`), all three
        sorts are available: `relevance`, `newest`, `plays`.

        **Filter rules (enforced server-side):**
        - `time_range` and `duration` only apply when `type=tracks`
        - `tag` applies to `tracks`, `playlists`, and `albums` — not `users`
        - `location` only applies when `type=users`
        - `filters` in the response is `null` when no `type` is specified

        Pagination is via `limit` and `offset`.
      security: []
      parameters:
        - name: q
          in: query
          required: true
          schema: { type: string, minLength: 2 }
          description: Search query. Must be at least 2 characters.
        - name: type
          in: query
          schema:
            type: string
            enum: [everything, tracks, users, playlists, albums]
          description: Resource type to search. Omit to search all types.
        - name: sort
          in: query
          schema:
            type: string
            enum: [relevance, newest, plays]
            default: relevance
          description: |
            Sort order. `plays` is not available when `type=everything`.
        - name: limit
          in: query
          schema: { type: integer, default: 20, minimum: 1, maximum: 100 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
        - name: time_range
          in: query
          schema:
            type: string
            enum: [past_hour, past_day, past_week, past_month, past_year]
          description: Filter tracks by upload recency. Only valid when `type=tracks`.
        - name: duration
          in: query
          schema:
            type: string
            enum: [short, medium, long, extra]
          description: |
            Filter tracks by duration. Only valid when `type=tracks`.
            - `short` — under 2 minutes
            - `medium` — 2–10 minutes
            - `long` — 10–30 minutes
            - `extra` — over 30 minutes
        - name: tag
          in: query
          schema: { type: string }
          description: Filter by tag. Valid for `tracks`, `playlists`, and `albums`. Not valid for `users`.
        - name: location
          in: query
          schema: { type: string }
          description: Filter users by location. Only valid when `type=users`.
      responses:
        '200':
          description: Search results returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'

  # Route is GET /suggestions mounted at /api/v1 (not /search/suggestions)
  # See search.routes.js: router.get('/suggestions', ...) + app.use(`${API}`, searchRoutes)
  /suggestions:
    get:
      tags: [Search]
      summary: Search autocomplete suggestions
      operationId: searchSuggestions
      description: |
        Returns up to 10 autocomplete suggestions for the given partial query.
        Minimum 1 character required. Intended for real-time typeahead UIs.
        Authentication is optional — results may be personalised when authenticated.
      security: []
      parameters:
        - name: q
          in: query
          required: true
          schema: { type: string, minLength: 1 }
          description: Partial search query. Must be at least 1 character.
        - name: limit
          in: query
          schema: { type: integer, default: 5, minimum: 1, maximum: 10 }
          description: Number of suggestions to return. Defaults to 5, max 10.
      responses:
        '200':
          description: Suggestion list returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchSuggestionsResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
  /resolve:
    get:
      description: Resolves a Rythmify permalink URL to its resource type and ID.
      tags: [Search]
      summary: Resolve permalink to resource
      operationId: resolvePermalink
      security: []
      parameters:
        - name: url
          in: query
          required: true
          schema: { type: string, format: uri }
      responses:
        '200':
          description: Permalink resolved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolveResponse'
        '400':
          description: Invalid URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'

  # ==========================================================
  # Module 9 — Messaging & Track Sharing
  # ==========================================================

  /messages/conversations:
    get:
      description: |
        Returns conversations for the authenticated user, sorted by most recent message.
        Uses offset-based pagination (`limit`, `offset`).
        Legacy `page` is accepted as a backward-compatible fallback.
      tags: [Messages]
      summary: List all conversations
      operationId: listConversations
      parameters:
        - name: page
          in: query
          deprecated: true
          description: Legacy page number. Use `offset` instead.
          schema: { type: integer, minimum: 1 }
        - name: limit
          in: query
          schema: { type: integer, default: 20, minimum: 1, maximum: 50 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
      responses:
        '200':
          description: Paginated list of conversations returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /messages/conversations/{conversationId}:
    get:
      description: |
        Returns a conversation and its message thread, paginated oldest-to-newest.
        Uses offset-based pagination (`limit`, `offset`).
        Legacy `page` is accepted as a fallback when `offset` is omitted.
      tags: [Messages]
      summary: Get a single conversation with messages
      operationId: getConversation
      parameters:
        - name: conversationId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: limit
          in: query
          schema: { type: integer, default: 50, minimum: 1, maximum: 100 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
      responses:
        '200':
          description: Conversation and messages returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationDetailResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      description: Soft-deletes the conversation for the authenticated user only.
      tags: [Messages]
      summary: Delete a conversation
      operationId: deleteConversation
      parameters:
        - name: conversationId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Conversation deleted for current user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /messages/conversations/{conversationId}/messages:
    post:
      description: Appends a new text or embedded resource message to an existing conversation.
      tags: [Messages]
      summary: Send a message in a conversation
      operationId: sendMessage
      parameters:
        - name: conversationId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
      responses:
        '201':
          description: Message sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageCreatedResponse'
        '400':
          description: Validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Sender blocked or messaging restricted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                blocked:
                  value:
                    error:
                      code: MESSAGES_BLOCKED
                      message: You cannot send a message to this user.
                disabled:
                  value:
                    error:
                      code: MESSAGES_DISABLED
                      message: This user does not accept messages from anyone.
                followersOnly:
                  value:
                    error:
                      code: MESSAGES_FOLLOWERS_ONLY
                      message: This user only accepts messages from people they follow.
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /messages/conversations/{conversationId}/messages/{messageId}:
    delete:
      description: Permanently deletes a message the authenticated user sent.
      tags: [Messages]
      summary: Delete a specific message
      operationId: deleteMessage
      parameters:
        - name: conversationId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: messageId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Message deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /messages/new:
    post:
      description: Creates a new direct message conversation and sends the first message.
      tags: [Messages]
      summary: Start a new conversation
      operationId: startConversation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartConversationRequest'
      responses:
        '201':
          description: Conversation created and first message sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationCreatedResponse'
        '200':
          description: Existing conversation found — message appended.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageCreatedResponse'
        '400':
          description: Validation failed or self-messaging.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Recipient has blocked sender or does not accept messages under current privacy settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                blocked:
                  value:
                    error:
                      code: MESSAGES_BLOCKED
                      message: You cannot send a message to this user.
                disabled:
                  value:
                    error:
                      code: MESSAGES_DISABLED
                      message: This user does not accept messages from anyone.
                followersOnly:
                  value:
                    error:
                      code: MESSAGES_FOLLOWERS_ONLY
                      message: This user only accepts messages from people they follow.
        '404':
          description: Recipient not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /messages/conversations/ensure:
    post:
      description: Returns an existing conversation or creates one if none exists, without sending a message.
      tags: [Messages]
      summary: Ensure a conversation exists
      operationId: ensureConversation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnsureConversationRequest'
      responses:
        '201':
          description: Conversation created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnsureConversationResponse'
        '200':
          description: Existing conversation returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnsureConversationResponse'
        '400':
          description: Validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Recipient policy blocks this sender.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Recipient not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /messages/unread-count:
    get:
      description: Returns the total unread message count across all conversations.
      tags: [Messages]
      summary: Get total unread message count
      operationId: getUnreadMessageCount
      responses:
        '200':
          description: Unread message count returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnreadCountResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /messages/conversations/{conversationId}/messages/{messageId}/read:
    patch:
      description: Sets the read or unread state of a single message.
      tags: [Messages]
      summary: Mark a message as read or unread
      operationId: markMessageReadState
      parameters:
        - name: conversationId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: messageId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkMessageReadRequest'
      responses:
        '200':
          description: Message read state updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkMessageReadResponse'
        '400':
          description: Missing or invalid is_read value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Message already in requested read state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # ==========================================================
  # Module 10 — Real-Time Notifications
  # [FIX-11] Corrected section label (was "Messaging & Track Sharing")
  # ==========================================================

  /notifications:
    get:
      description: Returns the authenticated user's paginated in-app notification feed.
      tags: [Notifications]
      summary: Get in-app notification feed
      operationId: getNotifications
      parameters:
        - name: page
          in: query
          description: 1-based page index.
          schema: { type: integer, default: 1, minimum: 1 }
        - name: limit
          in: query
          schema: { type: integer, default: 20, minimum: 1, maximum: 50 }
        - name: unread_only
          in: query
          description: |
            Read-state filter.
            - true: unread notifications only
            - false: read notifications only
            - omitted: all notifications
            Also accepts aliases `unread` and `unreadOnly`.
          schema: { type: boolean }
        - name: type
          in: query
          description: Filter by notification type.
          schema:
            type: string
            enum: [follow, like, repost, comment, new_post_by_followed]
      responses:
        '200':
          description: Notification feed returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /notifications/unread-count:
    get:
      description: Returns the total count of unread notifications for the authenticated user.
      tags: [Notifications]
      summary: Get unread notification count
      operationId: getUnreadNotificationCount
      responses:
        '200':
          description: Unread notification count returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnreadCountResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  # UNVERIFIED — no matching route found in src/routes/ as of audit date
  # markAllNotificationsRead does not exist in notifications.routes.js.
  /notifications/read-all:
    post:
      description: Marks all unread notifications as read and resets the unread counter.
      tags: [Notifications]
      summary: Mark all notifications as read
      operationId: markAllNotificationsRead
      responses:
        '200':
          description: All notifications marked as read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /notifications/{notification_id}/read:
    patch:
      description: Marks a single notification as read.
      tags: [Notifications]
      summary: Mark a single notification as read
      operationId: markNotificationRead
      parameters:
        - name: notification_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Notification marked as read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  # UNVERIFIED — no matching route found in src/routes/ as of audit date
  # DELETE /notifications/{notification_id} does not exist in notifications.routes.js.
  # Only PATCH /{notification_id}/read is implemented.
  /notifications/{notification_id}:
    delete:
      description: Permanently removes a single notification from the user's feed.
      tags: [Notifications]
      summary: Delete a notification
      operationId: deleteNotification
      parameters:
        - name: notification_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Notification deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /notifications/push/register:
    post:
      description: Registers a device push token for FCM or APNs delivery.
      tags: [Notifications]
      summary: Register a device push token
      operationId: registerPushToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterPushTokenRequest'
      responses:
        '200':
          description: Push token registered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
        '400':
          description: Missing or malformed token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /notifications/push/unregister:
    post:
      description: Removes a device push token to stop push notifications on that device.
      tags: [Notifications]
      summary: Unregister a device push token
      operationId: unregisterPushToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnregisterPushTokenRequest'
      responses:
        '200':
          description: Push token removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
        '400':
          description: Missing token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Token not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'

  /notifications/preferences:
    get:
      description: Returns the authenticated user's full notification preference flags.
      tags: [Notifications]
      summary: Get notification preferences
      operationId: getNotificationPreferences
      responses:
        '200':
          description: Notification preferences returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationPreferencesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    patch:
      description: Partially updates the authenticated user's notification preference flags.
      tags: [Notifications]
      summary: Update notification preferences
      operationId: updateNotificationPreferences
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNotificationPreferencesRequest'
      responses:
        '200':
          description: Preferences updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationPreferencesResponse'
        '400':
          description: Invalid preference field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  # ==========================================================
  # Module 11 — Moderation & Admin Dashboard
  # ==========================================================

  /reports:
    post:
      tags: [Moderation]
      summary: Submit a content report
      description: |
        Report a track or user. Rate limit: 10 reports per hour per user.
        `copyright` reason is only valid for tracks, not users.
      operationId: submitReport
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportRequest'
      responses:
        '201':
          description: Report submitted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Report'
                  message:
                    type: string
                    example: Report submitted successfully.
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Reported resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Already reported this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'

  /admin/reports:
    get:
      description: Returns all submitted content reports for admin review, with optional filters.
      tags: [Admin]
      summary: List all reports (admin only)
      operationId: listAdminReports
      parameters:
        - name: status
          in: query
          schema: { type: string, enum: [pending, resolved, dismissed] }
        - name: reason
          in: query
          schema: { type: string, enum: [copyright, inappropriate, spam, impersonation] }
        - name: limit
          in: query
          schema: { type: integer, default: 20, minimum: 1, maximum: 100 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
      responses:
        '200':
          description: Reports returned.
          content:
            application/json:
              schema:
                type: object
                required: [data, pagination]
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReportDetailed'
                  pagination:
                    $ref: '#/components/schemas/ListMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /admin/reports/{id}:
    get:
      description: Returns the full details of a single content report by ID.
      tags: [Admin]
      summary: Get a single report (admin only)
      operationId: getAdminReport
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Report returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ReportDetailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      description: Updates a report's status to resolved or dismissed with an optional admin note.
      tags: [Admin]
      summary: Resolve or dismiss a report (admin only)
      operationId: resolveAdminReport
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status:
                  type: string
                  enum: [resolved, dismissed]
                admin_note:
                  type: string
      responses:
        '200':
          description: Report updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      status:
                        type: string
                        enum: [resolved, dismissed]
                      resolved_at:
                        type: string
                        format: date-time
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /admin/tracks/{id}:
    delete:
      description: Permanently deletes a track and all its data from the platform.
      tags: [Admin]
      summary: Delete a track (admin only)
      operationId: adminDeleteTrack
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '204':
          description: Track deleted. No response body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      description: Sets the is_hidden flag on a track to suppress it from public view.
      tags: [Admin]
      summary: Hide/unhide a track (admin only)
      operationId: adminToggleTrackVisibility
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [is_hidden]
              properties:
                is_hidden:
                  type: boolean
                reason:
                  type: string
      responses:
        '200':
          description: Track visibility updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      track_id:
                        type: string
                        format: uuid
                      is_hidden:
                        type: boolean
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /admin/users/{id}/suspend:
    patch:
      description: Suspends a user account, blocking login and all platform activity.
      tags: [Admin]
      summary: Suspend a user account (admin only)
      operationId: adminSuspendUser
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [reason]
              properties:
                reason:
                  type: string
                  example: Repeated copyright violations
      responses:
        '200':
          description: Account suspended.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      status:
                        type: string
                        example: suspended
                      reason:
                        type: string
                      suspended_at:
                        type: string
                        format: date-time
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: Cannot suspend admin account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /admin/users/{id}/reinstate:
    patch:
      description: Restores access to a previously suspended user account.
      tags: [Admin]
      summary: Reinstate a suspended account (admin only)
      operationId: adminReinstateUser
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Account reinstated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      status:
                        type: string
                        example: active
                      reinstated_at:
                        type: string
                        format: date-time
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /admin/analytics:
    get:
      description: Returns high-level platform metrics for the specified reporting period.
      tags: [Admin]
      summary: Get platform analytics (admin only)
      operationId: getAdminAnalytics
      parameters:
        - name: period
          in: query
          schema: { type: string, enum: [day, week, month], default: month }
      responses:
        '200':
          description: Analytics returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AnalyticsSummary'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /admin/users/{id}/warn:
    post:
      description: Send a warning to a user before taking punitive actions. Includes reason and optional message. Warning can be escalated to suspension if ignored.
      tags: [Admin]
      summary: Send warning to user (admin only)
      operationId: warnUser
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [reason]
              properties:
                reason:
                  type: string
                  enum: [copyright_strike, repeated_reports, content_policy_violation, spam]
                  description: Category of warning
                message:
                  type: string
                  maxLength: 500
                  description: Custom message to user
      responses:
        '200':
          description: Warning issued to user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      user_id:
                        type: string
                        format: uuid
                      warning_count:
                        type: integer
                      warned_at:
                        type: string
                        format: date-time
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /admin/reports/{id}/appeal:
    post:
      description: Create an appeal request for a report that was resolved/dismissed. User can provide additional context. Admins review appeal separately.
      tags: [Admin]
      summary: Appeal a report decision (user can initiate)
      operationId: appealReport
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [appeal_reason]
              properties:
                appeal_reason:
                  type: string
                  maxLength: 1000
                  description: User's explanation for appeal
      responses:
        '200':
          description: Appeal submitted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ReportAppeal'
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Report cannot be appealed (still pending or already appealed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /admin/appeals:
    get:
      description: List all pending report appeals for admin review. Includes original report and appeal reason.
      tags: [Admin]
      summary: List report appeals (admin only)
      operationId: listReportAppeals
      parameters:
        - name: status
          in: query
          schema: { type: string, enum: [pending, upheld, overturned], default: pending }
        - name: limit
          in: query
          schema: { type: integer, default: 20, minimum: 1, maximum: 100 }
        - name: offset
          in: query
          schema: { type: integer, default: 0, minimum: 0 }
      responses:
        '200':
          description: Appeals returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReportAppeal'
                  pagination:
                    $ref: '#/components/schemas/ListMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /admin/appeals/{id}:
    get:
      description: Returns the full details of a single report appeal by ID.
      tags: [Admin]
      summary: Get a single appeal (admin only)
      operationId: getAdminAppeal
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Appeal returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ReportAppeal'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      description: Review and decide on an appeal (uphold original decision or overturn it).
      tags: [Admin]
      summary: Review appeal decision (admin only)
      operationId: reviewAppeal
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [decision]
              properties:
                decision:
                  type: string
                  enum: [upheld, overturned]
                admin_notes:
                  type: string
                  maxLength: 500
      responses:
        '200':
          description: Appeal decision recorded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      decision:
                        type: string
                      decided_at:
                        type: string
                        format: date-time
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  # ==========================================================
  # Module 12 — Premium Subscription & Payments
  # ==========================================================

  /subscriptions/plans:
    get:
      description: |
        Public endpoint that returns available subscription plan display variants.

        Without authentication, the response is a marketing view with Free, Go+, and Artist Pro.
        Go+ and Artist Pro both represent the same real backend `premium` plan and share the
        same `subscription_plan_id`. With a valid Bearer token, the response contains Free plus
        the premium display variant for the authenticated user's role.

        Plan limits:
        - Free plan has `track_limit=3`, `playlist_limit=2`, and standard streaming access.
        - Go+ keeps premium benefits but displays the free upload limit for listener-facing marketing.
        - Artist Pro displays unlimited uploads with `track_limit=null`.
        - This demo/testing backend uses a 5-minute premium period, exposed as `duration_minutes=5`.
        - `duration_days` remains nullable for backward compatibility.
      tags: [Subscription]
      summary: List available subscription plans
      operationId: listSubscriptionPlans
      security:
        - bearerAuth: []
        - {}
      responses:
        '200':
          description: Subscription plans returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionPlanListResponse'
              example:
                data:
                  items:
                    - subscription_plan_id: 1
                      name: free
                      display_name: Free
                      price: '0.00'
                      duration_days: null
                      duration_minutes: null
                      track_limit: 3
                      playlist_limit: 2
                    - subscription_plan_id: 2
                      name: premium
                      display_name: Go+
                      price: '4.99'
                      duration_days: null
                      duration_minutes: 5
                      track_limit: 3
                      playlist_limit: null
                    - subscription_plan_id: 2
                      name: premium
                      display_name: Artist Pro
                      price: '4.99'
                      duration_days: null
                      duration_minutes: 5
                      track_limit: null
                      playlist_limit: null
                message: Subscription plans fetched successfully.
        '429':
          $ref: '#/components/responses/RateLimited'

  /subscriptions/me:
    get:
      description: |
        Returns the authenticated user's effective current subscription.

        This endpoint does not return 404 just because the user has no premium subscription. Every authenticated user has an effective subscription view. If the user has no active premium subscription, the response returns the free plan with current usage and limits.

        Notes:
        - `user_subscription_id` is `null` only for the default effective free plan.
        - Nullable numeric limits mean unlimited.
        - `can_upload_track` and `can_create_playlist` are computed from plan limits and current usage.
        - `offline_listening_enabled` is true only for active premium users.
        - Expired premium subscriptions are refreshed lazily. Auto-renewing demo premium periods renew in 5-minute increments; canceled subscriptions expire back to Free after `end_date`.
      tags: [Subscription]
      summary: Get current user subscription
      operationId: getMySubscription
      responses:
        '200':
          description: Current subscription returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MySubscriptionResponse'
              examples:
                free:
                  summary: Effective free plan
                  value:
                    data:
                      user_subscription_id: null
                      status: active
                      auto_renew: false
                      start_date: null
                      end_date: null
                      plan:
                        subscription_plan_id: 1
                        name: free
                        display_name: Free
                        price: '0.00'
                        duration_days: null
                        duration_minutes: null
                        track_limit: 3
                        playlist_limit: 2
                      usage:
                        tracks_uploaded: 2
                        track_limit: 3
                        playlists_created: 1
                        playlist_limit: 2
                        can_upload_track: true
                        can_create_playlist: true
                        offline_listening_enabled: false
                    message: Subscription fetched successfully.
                premium_listener:
                  summary: Active premium plan for a listener
                  value:
                    data:
                      user_subscription_id: 12
                      status: active
                      auto_renew: true
                      start_date: '2026-04-24T20:30:00Z'
                      end_date: '2026-04-24T20:35:00Z'
                      plan:
                        subscription_plan_id: 2
                        name: premium
                        display_name: Go+
                        price: '4.99'
                        duration_days: null
                        duration_minutes: 5
                        track_limit: 3
                        playlist_limit: null
                      usage:
                        tracks_uploaded: 20
                        track_limit: 3
                        playlists_created: 10
                        playlist_limit: null
                        can_upload_track: true
                        can_create_playlist: true
                        offline_listening_enabled: true
                    message: Subscription fetched successfully.
                premium_artist:
                  summary: Active premium plan for an artist
                  value:
                    data:
                      user_subscription_id: 12
                      status: active
                      auto_renew: true
                      start_date: '2026-04-24T20:30:00Z'
                      end_date: '2026-04-24T20:35:00Z'
                      plan:
                        subscription_plan_id: 2
                        name: premium
                        display_name: Artist Pro
                        price: '4.99'
                        duration_days: null
                        duration_minutes: 5
                        track_limit: null
                        playlist_limit: null
                      usage:
                        tracks_uploaded: 20
                        track_limit: null
                        playlists_created: 10
                        playlist_limit: null
                        can_upload_track: true
                        can_create_playlist: true
                        offline_listening_enabled: true
                    message: Subscription fetched successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /subscriptions/checkout:
    post:
      description: |
        Creates a mocked Stripe/Test Mode style checkout session for a paid subscription plan.

        Lifecycle:
        - Only the paid premium plan is eligible for checkout.
        - The free plan should not go through checkout.
        - Checkout creates a pending `user_subscription` and pending transaction.
        - Checkout does not activate premium immediately.
        - Premium is activated only after `POST /subscriptions/mock-confirm/{transaction_id}`.
        - For demo/testing, confirmed premium access lasts 5 minutes and then renews lazily when eligible.
      tags: [Subscription]
      summary: Start subscription checkout
      operationId: createSubscriptionCheckout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionCheckoutRequest'
      responses:
        '200':
          description: Checkout session created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionCheckoutResponse'
              example:
                data:
                  transaction_id: 55
                  user_subscription_id: 12
                  checkout_status: pending
                  payment_method: mock
                  payment_url: https://mock-stripe.rythmify.local/checkout/55
                  plan:
                    subscription_plan_id: 2
                    name: premium
                    display_name: Go+
                    price: '4.99'
                    duration_days: null
                    duration_minutes: 5
                    track_limit: 3
                    playlist_limit: null
                message: Mock subscription checkout created successfully.
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Already has an active subscription or pending checkout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Plan not eligible for checkout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'

  /subscriptions/cancel:
    post:
      description: Disables auto-renew for the authenticated user's active premium subscription. The subscription remains `active` until its 5-minute demo `end_date`, then expires unless renewed. If `auto_renew` is already false, the endpoint returns 409.
      tags: [Subscription]
      summary: Cancel current subscription
      operationId: cancelMySubscription
      responses:
        '200':
          description: Subscription auto-renew canceled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelSubscriptionResponse'
              example:
                data:
                  user_subscription_id: 12
                  status: active
                  auto_renew: false
                  end_date: '2026-04-24T20:35:00Z'
                message: Subscription auto-renew canceled successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No active subscription found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Already canceled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'

  /subscriptions/me/dev-reset:
    post:
      tags: ['Subscriptions - Development Only']
      summary: Reset current user's subscription for local testing
      operationId: resetMySubscriptionForDevelopmentTesting
      description: |
        Development-only endpoint available only when `NODE_ENV=development`.

        Expires the authenticated user's active/pending premium subscription, disables auto-renew, keeps transaction history, and returns the effective free subscription state. Intended only for FE/mobile/BE testing of checkout, expiration, cancellation, and renewal flows.

        Safety notes:
        - Requires bearer authentication.
        - Resets only the authenticated current user's subscription.
        - Does not reset other users.
        - Does not delete transaction history.
        - Does not require any new environment variable.
        - No reset-all endpoint exists.
      responses:
        '200':
          description: Current user's subscription reset for local development testing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MySubscriptionResponse'
              example:
                data:
                  user_subscription_id: null
                  status: active
                  auto_renew: false
                  start_date: null
                  end_date: null
                  plan:
                    subscription_plan_id: 1
                    name: free
                    display_name: Free
                    price: '0.00'
                    duration_days: null
                    duration_minutes: null
                    track_limit: 3
                    playlist_limit: 2
                  usage:
                    tracks_uploaded: 2
                    track_limit: 3
                    playlists_created: 1
                    playlist_limit: 2
                    can_upload_track: true
                    can_create_playlist: true
                    offline_listening_enabled: false
                message: Subscription reset for development testing successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Endpoint is not registered outside development, or test tools are disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: SUBSCRIPTION_TEST_TOOLS_DISABLED
                  message: This endpoint is only available in development.
        '429':
          $ref: '#/components/responses/RateLimited'

  /subscriptions/transactions:
    get:
      description: |
        Returns the authenticated user's subscription transaction history.

        Supports `limit`/`offset` pagination and optional `payment_status` filtering. Transactions are returned newest first.
      tags: [Subscription]
      summary: List subscription transactions
      operationId: listMySubscriptionTransactions
      parameters:
        - name: limit
          in: query
          description: Page size.
          schema: { type: integer, minimum: 1, maximum: 50, default: 20 }
        - name: offset
          in: query
          description: Pagination offset.
          schema: { type: integer, minimum: 0, default: 0 }
        - name: payment_status
          in: query
          description: Optional payment status filter.
          schema:
            $ref: '#/components/schemas/PaymentStatus'
      responses:
        '200':
          description: Transactions returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionTransactionListResponse'
              example:
                data:
                  - transaction_id: 55
                    user_subscription_id: 12
                    amount: '4.99'
                    payment_method: mock
                    payment_status: paid
                    paid_at: '2026-04-24T20:30:00Z'
                    created_at: '2026-04-24T20:29:00Z'
                pagination:
                  limit: 20
                  offset: 0
                  total: 1
                message: Subscription transactions fetched successfully.
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /subscriptions/mock-confirm/{transaction_id}:
    post:
      description: |
        Simulates successful Stripe payment confirmation.

        Effects:
        - Marks the transaction `payment_status` as `paid`.
        - Activates the linked user subscription.
        - Sets subscription `status` to `active`.
        - Sets `start_date` and `end_date` to date-time values.
        - Enables premium entitlements after success.
        - For demo/testing, premium `end_date` is 5 minutes after `start_date`.
        - Re-confirming an already paid transaction returns 409.
      tags: [Subscription]
      summary: Confirm mocked subscription payment
      operationId: confirmMockSubscriptionPayment
      parameters:
        - name: transaction_id
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Mock payment confirmed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MockConfirmSubscriptionResponse'
              example:
                data:
                  transaction_id: 55
                  payment_status: paid
                  paid_at: '2026-04-24T20:30:00Z'
                  subscription:
                    user_subscription_id: 12
                    status: active
                    auto_renew: true
                    start_date: '2026-04-24T20:30:00Z'
                    end_date: '2026-04-24T20:35:00Z'
                    plan:
                      subscription_plan_id: 2
                      name: premium
                      display_name: Go+
                      price: '4.99'
                      duration_days: null
                      duration_minutes: 5
                      track_limit: 3
                      playlist_limit: null
                message: Mock subscription payment confirmed successfully.
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Transaction not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Already paid or not pending.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'

  # ==========================================================
  # Module 3 — Followers & Social Graph
  # ==========================================================

  /users/{user_id}/follow:
    post:
      description: Creates a follow relationship from the authenticated user to the target user.
      tags: [Follow]
      summary: Follow a user
      operationId: followUser
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Already following — no change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '201':
          description: Followed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FollowResponse'
        '400':
          description: Cannot follow yourself.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Block relationship exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      description: Removes the follow relationship from the authenticated user to the target user.
      tags: [Follow]
      summary: Unfollow a user
      operationId: unfollowUser
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '204':
          description: Unfollowed — no body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /users/{user_id}/followers:
    get:
      description: Returns a paginated list of users who follow the specified user.
      tags: [Follow]
      summary: List a user's followers
      operationId: getFollowers
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated followers list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /users/{user_id}/following:
    get:
      description: Returns a paginated list of users the specified user follows.
      tags: [Follow]
      summary: List users that a user follows
      operationId: getFollowing
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated following list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /users/{user_id}/follow-status:
    get:
      description: Returns the follow and block relationship between the caller and the target user.
      tags: [Follow]
      summary: Check relationship status between me and a user
      operationId: getFollowStatus
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Relationship status returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/FollowStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /users/suggested:
    get:
      description: Returns suggested users to follow from mutual connections and popular accounts. Response uses ListMeta pagination in the `pagination` object.
      tags: [Follow Discovery]
      summary: Get suggested users to follow
      operationId: getSuggestedUsers
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Suggested users returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuggestedUsersResponse'
              example:
                data:
                  - id: 11111111-1111-1111-1111-111111111111
                    display_name: Alice Wave
                    username: alicewave
                    profile_picture: https://cdn.rythmify.com/avatars/alice.jpg
                    is_verified: true
                    follower_count: 1240
                    mutual_count: 4
                    suggestion_source: mutual
                    is_following: false
                pagination:
                  limit: 20
                  offset: 0
                  total: 340
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /users/suggested/artists:
    get:
      description: Returns suggested artists to follow based on the user's liked-track genre history. Response uses ListMeta pagination in the `pagination` object.
      tags: [Follow Discovery]
      summary: Get suggested artists to follow
      operationId: getSuggestedArtists
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Suggested artists returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuggestedArtistsResponse'
              example:
                data:
                  - id: 22222222-2222-2222-2222-222222222222
                    display_name: Echo Atlas
                    username: echoatlas
                    profile_picture: https://cdn.rythmify.com/avatars/echo.jpg
                    is_verified: false
                    follower_count: 870
                    top_genre: electronic
                    is_following: false
                pagination:
                  limit: 20
                  offset: 0
                  total: 210
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /users/{user_id}/block:
    post:
      description: Blocks the target user, removing any existing follow relationships.
      tags: [Block]
      summary: Block a user
      operationId: blockUser
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Already blocked — no change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '201':
          description: User blocked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockResponse'
        '400':
          description: Cannot block yourself.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      description: Removes the block on the target user.
      tags: [Block]
      summary: Unblock a user
      operationId: unblockUser
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '204':
          description: Unblocked — no body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /users/me/blocked:
    get:
      description: Returns a paginated list of all users blocked by the authenticated user.
      tags: [Block]
      summary: List users I have blocked
      operationId: getBlockedUsers
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated blocked users list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /users/me/follow-requests:
    get:
      description: Returns a paginated list of pending follow requests to the authenticated user (on private accounts).
      tags: [Follow]
      summary: List pending follow requests
      operationId: getPendingFollowRequests
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated pending follow requests list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /users/me/follow-requests/{request_id}/accept:
    post:
      description: Accepts a pending follow request and creates a follow relationship.
      tags: [Follow]
      summary: Accept a follow request
      operationId: acceptFollowRequest
      parameters:
        - name: request_id
          in: path
          required: true
          description: The follow request UUID
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Follow request already accepted — no change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '201':
          description: Follow request accepted. User is now following.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FollowRequestResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Follow request not found or already processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /users/me/follow-requests/{request_id}/reject:
    post:
      description: Rejects a pending follow request without creating a follow relationship.
      tags: [Follow]
      summary: Reject a follow request
      operationId: rejectFollowRequest
      parameters:
        - name: request_id
          in: path
          required: true
          description: The follow request UUID
          schema: { type: string, format: uuid }
      responses:
        '204':
          description: Follow request rejected — no body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Follow request not found or already processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /users/me/follow-requests/{request_id}:
    delete:
      description: Cancels a follow request sent by the authenticated user.
      tags: [Follow]
      summary: Cancel a follow request
      operationId: cancelFollowRequest
      parameters:
        - name: request_id
          in: path
          required: true
          description: The follow request UUID
          schema: { type: string, format: uuid }
      responses:
        '204':
          description: Follow request canceled — no body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Follow request not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /users/me/following:
    get:
      tags: [Follow]
      summary: Get or search my following list
      description: |
        Returns users the authenticated user follows.
        With `q`, filters by display_name or username (debounce at 300ms client-side).
        Used for new conversation user picker.
      operationId: getMyFollowing
      parameters:
        - name: q
          in: query
          schema: { type: string, minLength: 1, maxLength: 100 }
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Following list returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FollowingSearchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  # ==========================================================
  # Module 6 — Engagement & Social Interactions
  # ==========================================================

  /tracks/{track_id}/like:
    post:
      description: Records a like on the specified track for the authenticated user.
      tags: [Likes]
      summary: Like a track
      operationId: likeTrack
      parameters:
        - $ref: '#/components/parameters/TrackId'
      responses:
        '200':
          description: Already liked — no change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '201':
          description: Track liked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LikeResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      description: Removes the authenticated user's like from the specified track.
      tags: [Likes]
      summary: Unlike a track
      operationId: unlikeTrack
      parameters:
        - $ref: '#/components/parameters/TrackId'
      responses:
        '204':
          description: Unliked — no body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /tracks/{track_id}/likers:
    get:
      description: Returns a paginated list of users who liked the specified track.
      tags: [Likes]
      summary: List users who liked a track
      operationId: getTrackLikers
      parameters:
        - $ref: '#/components/parameters/TrackId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated likers list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /tracks/{track_id}/repost:
    post:
      description: Reposts the specified track to the authenticated user's profile.
      tags: [Reposts]
      summary: Repost a track
      operationId: repostTrack
      parameters:
        - $ref: '#/components/parameters/TrackId'
      responses:
        '200':
          description: Already reposted — no change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '201':
          description: Track reposted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepostResponse'
        '400':
          description: Cannot repost own track.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      description: Removes the authenticated user's repost of the specified track.
      tags: [Reposts]
      summary: Remove a repost
      operationId: removeRepost
      parameters:
        - $ref: '#/components/parameters/TrackId'
      responses:
        '204':
          description: Repost removed — no body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /tracks/{track_id}/reposters:
    get:
      description: Returns a paginated list of users who reposted the specified track.
      tags: [Reposts]
      summary: List users who reposted a track
      operationId: getTrackReposters
      parameters:
        - $ref: '#/components/parameters/TrackId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated reposters list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  # ==========================================================
  # Module 3 — Comments & Track Comments (Waveform Flyovers)
  # ==========================================================
  # For floating comments displayed during playback (waveform flyovers):
  # The frontend monitors the current playback position and displays comments
  # whose track_timestamp is close to that position. Use the new query
  # parameters (timestamp_from, timestamp_to, sort=timestamp) to load comments
  # for a specific waveform section efficiently instead of fetching all comments.
  #
  # CRITICAL DATABASE REQUIREMENTS:
  # 1. ALTER TABLE comments ADD COLUMN updated_at TIMESTAMPTZ;
  #    — Required for PATCH (edit) endpoint to track last modification.
  #
  # 2. ALTER TABLE comments ADD COLUMN reply_count INTEGER DEFAULT 0;
  #    — Denormalized counter (must be kept up-to-date via triggers or app logic).
  #      Avoids O(n) COUNT subqueries during pagination with thousands of comments.
  #      Increment on POST /comments/{comment_id}/replies
  #      Decrement on DELETE reply
  #
  # 3. CREATE INDEX ON comments (track_id, "timestamp");
  #    — Essential for fast waveform timestamp filtering/sorting.
  #      Queries with sort=timestamp or timestamp_from/timestamp_to will be sequential scans without it.
  #
  # 4. Foreign key: parent_comment_id REFERENCES comments(id) ON DELETE CASCADE
  #    — Required for cascade-delete behavior (DELETE comment deletes all nested replies).
  #      Alternative: implement cascade logic explicitly in DELETE endpoint handler.
  # ==========================================================

  /tracks/{track_id}/comments:
    get:
      description: |
        Returns paginated top-level comments for the specified track.

        Supports optional filtering by timestamp range and sorting strategies:
        - `timestamp_from` + `timestamp_to` — Filter comments to a specific waveform time window (in seconds).
        - `sort` — Change the sort order:
          - `newest` — Most recent comments first, then by id (default for browsing)
            SQL: ORDER BY created_at DESC, id DESC
          - `oldest` — Oldest comments first, then by id
            SQL: ORDER BY created_at ASC, id ASC
          - `timestamp` — Ordered by track_timestamp, then created_at, then id (deterministic, useful for waveform flyovers)
            SQL: ORDER BY track_timestamp ASC, created_at ASC, id ASC
          - `top` — Most-liked comments first, then by track_timestamp, then by created_at (ideal for highlights view)
            SQL: ORDER BY like_count DESC, track_timestamp ASC, created_at ASC, id ASC

        **Deterministic sorting:** Pagination is applied after filtering. Ties are ALWAYS broken by created_at (microsecond precision) and then id (UUID), ensuring:
        - Identical query results across multiple requests
        - No comment jumping or reordering
        - Stable pagination (no duplicates or skips)
      tags: [Comments]
      summary: List top-level comments on a track
      operationId: getTrackComments
      parameters:
        - $ref: '#/components/parameters/TrackId'
        - name: timestamp_from
          in: query
          required: false
          description: Show only comments at or after this timestamp (in seconds). Useful for waveform flyovers.
          schema: { type: integer, minimum: 0 }
        - name: timestamp_to
          in: query
          required: false
          description: Show only comments before or at this timestamp (in seconds). Useful for waveform flyovers.
          schema: { type: integer, minimum: 0 }
        - name: sort
          in: query
          required: false
          description: Sort order for comments.
          schema:
            type: string
            enum: [newest, oldest, timestamp, top]
            default: newest
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated top-level comments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      description: Posts a new timestamped comment on the specified track.
      tags: [Comments]
      summary: Post a comment on a track
      operationId: createComment
      parameters:
        - $ref: '#/components/parameters/TrackId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCommentRequest'
      responses:
        '201':
          description: Comment created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentCreatedResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /comments/{comment_id}:
    get:
      description: Returns a single comment by its ID.
      tags: [Comments]
      summary: Get a single comment
      operationId: getComment
      parameters:
        - $ref: '#/components/parameters/CommentId'
      responses:
        '200':
          description: Comment returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentSingleResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      description: |
        Updates the body text of a comment owned by the authenticated user.

        **Database requirement:** The comments table must have an `updated_at TIMESTAMPTZ` column.
        Backend must update this timestamp on every PATCH to track comment edits.
      tags: [Comments]
      summary: Edit a comment
      operationId: updateComment
      parameters:
        - $ref: '#/components/parameters/CommentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCommentRequest'
      responses:
        '200':
          description: Comment updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentSingleResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Not the comment author.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      description: |
        Deletes a comment and all its nested replies (cascade delete).

        **Database requirement:** The foreign key `parent_comment_id` must use `ON DELETE CASCADE`.
        Alternative: handle cascade explicitly in application code (delete all replies where parent_comment_id = :id first, then delete the parent).
      tags: [Comments]
      summary: Delete a comment
      operationId: deleteComment
      parameters:
        - $ref: '#/components/parameters/CommentId'
      responses:
        '204':
          description: Comment deleted — no body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /comments/{comment_id}/replies:
    get:
      description: |
        Returns paginated replies to the specified top-level comment.

        Replies are always ordered by creation time (oldest first), with id as final tie-breaker.
        This ensures deterministic, consistent pagination across requests.
      tags: [Comments]
      summary: List replies to a comment
      operationId: getCommentReplies
      parameters:
        - $ref: '#/components/parameters/CommentId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated replies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentListResponse'
        '400':
          description: Cannot list replies of a reply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      description: |
        Posts a reply to the specified top-level comment.

        **Database requirement:** Backend must increment the parent comment's `reply_count` field on successful POST.
        This denormalized counter is critical for pagination performance when listing comments.
      tags: [Comments]
      summary: Reply to a comment
      operationId: replyToComment
      parameters:
        - $ref: '#/components/parameters/CommentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReplyRequest'
      responses:
        '201':
          description: Reply posted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentCreatedResponse'
        '400':
          description: Nesting depth exceeded or validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /comments/{comment_id}/like:
    post:
      description: Records a like on the specified comment for the authenticated user.
      tags: [Likes]
      summary: Like a comment
      operationId: likeComment
      parameters:
        - $ref: '#/components/parameters/CommentId'
      responses:
        '200':
          description: Already liked — no change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '201':
          description: Comment liked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentLikeResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      description: Removes the authenticated user's like from the specified comment.
      tags: [Likes]
      summary: Unlike a comment
      operationId: unlikeComment
      parameters:
        - $ref: '#/components/parameters/CommentId'
      responses:
        '204':
          description: Unliked — no body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /playlists/{playlist_id}/like:
    post:
      description: Records a like on the specified playlist for the authenticated user.
      tags: [Likes]
      summary: Like a playlist
      operationId: likePlaylist
      parameters:
        - $ref: '#/components/parameters/PlaylistId'
      responses:
        '200':
          description: Already liked — no change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '201':
          description: Playlist liked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistLikeResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      description: Removes the authenticated user's like from the specified playlist.
      tags: [Likes]
      summary: Unlike a playlist
      operationId: unlikePlaylist
      parameters:
        - $ref: '#/components/parameters/PlaylistId'
      responses:
        '204':
          description: Unliked — no body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /playlists/{playlist_id}/likers:
    get:
      description: Returns a paginated list of users who liked the specified playlist.
      tags: [Likes]
      summary: List users who liked a playlist
      operationId: getPlaylistLikers
      parameters:
        - $ref: '#/components/parameters/PlaylistId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated likers list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /playlists/{playlist_id}/repost:
    post:
      description: Reposts the specified playlist to the authenticated user's profile.
      tags: [Reposts]
      summary: Repost a playlist
      operationId: repostPlaylist
      parameters:
        - $ref: '#/components/parameters/PlaylistId'
      responses:
        '200':
          description: Already reposted — no change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '201':
          description: Playlist reposted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistRepostResponse'
        '400':
          description: Cannot repost own playlist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      description: Removes the authenticated user's repost of the specified playlist.
      tags: [Reposts]
      summary: Remove a playlist repost
      operationId: removePlaylistRepost
      parameters:
        - $ref: '#/components/parameters/PlaylistId'
      responses:
        '204':
          description: Repost removed — no body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /playlists/{playlist_id}/reposters:
    get:
      description: Returns a paginated list of users who reposted the specified playlist.
      tags: [Reposts]
      summary: List users who reposted a playlist
      operationId: getPlaylistReposters
      parameters:
        - $ref: '#/components/parameters/PlaylistId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated reposters list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  # ==========================================================
  # Module 6.5 — Likes & Reposts for Albums
  # ==========================================================

  /albums/{album_id}/like:
    post:
      description: Records a like on the specified album for the authenticated user.
      tags: [Likes]
      summary: Like an album
      operationId: likeAlbum
      parameters:
        - name: album_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Already liked — no change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '201':
          description: Album liked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlbumLikeResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      description: Removes the authenticated user's like from the specified album.
      tags: [Likes]
      summary: Unlike an album
      operationId: unlikeAlbum
      parameters:
        - name: album_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '204':
          description: Unliked — no body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /albums/{album_id}/likers:
    get:
      description: Returns a paginated list of users who liked the specified album.
      tags: [Likes]
      summary: List users who liked an album
      operationId: getAlbumLikers
      parameters:
        - name: album_id
          in: path
          required: true
          schema: { type: string, format: uuid }
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated likers list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /albums/{album_id}/repost:
    post:
      description: Reposts the specified album to the authenticated user's profile.
      tags: [Reposts]
      summary: Repost an album
      operationId: repostAlbum
      parameters:
        - name: album_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Already reposted — no change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '201':
          description: Album reposted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlbumRepostResponse'
        '400':
          description: Cannot repost own album.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      description: Removes the authenticated user's repost of the specified album.
      tags: [Reposts]
      summary: Remove an album repost
      operationId: removeAlbumRepost
      parameters:
        - name: album_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '204':
          description: Repost removed — no body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /albums/{album_id}/reposters:
    get:
      description: Returns a paginated list of users who reposted the specified album.
      tags: [Reposts]
      summary: List users who reposted an album
      operationId: getAlbumReposters
      parameters:
        - name: album_id
          in: path
          required: true
          schema: { type: string, format: uuid }
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated reposters list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  # ==========================================================
  # Module 6.6 — User Liked & Reposted Content Lists
  # ==========================================================

  /users/{user_id}/reposted-tracks:
    get:
      description: |
        Returns a paginated list of tracks reposted by the specified user.

        Access rules:
        - If the requested user's profile is public, the list is accessible to anyone.
        - If the requested user's profile is private, unauthenticated requests (guests) will immediately receive a 403 Forbidden.
        - If the profile is private and the requester is authenticated but not following the user, returns a 403 Forbidden.
      tags: [Reposts]
      summary: Get a user's reposted tracks
      operationId: getUserRepostedTracks
      security: []
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated list of reposted tracks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackListResponse'
        '403':
          description: Profile is private and requester does not have access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /me/liked-tracks:
    get:
      description: Returns a paginated list of tracks liked by the authenticated user.
      tags: [Likes]
      summary: List my liked tracks
      operationId: getMyLikedTracks
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated liked tracks list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /me/liked-playlists:
    get:
      description: Returns a paginated list of playlists liked by the authenticated user.
      tags: [Likes]
      summary: List my liked playlists
      operationId: getMyLikedPlaylists
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated liked playlists list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /me/liked-albums:
    get:
      description: Returns a paginated list of albums liked by the authenticated user.
      tags: [Likes]
      summary: List my liked albums
      operationId: getMyLikedAlbums
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated liked albums list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /me/reposted-tracks:
    get:
      description: Returns a paginated list of tracks reposted by the authenticated user.
      tags: [Reposts]
      summary: List my reposted tracks
      operationId: getMyRepostedTracks
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated reposted tracks list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /me/reposted-playlists:
    get:
      description: Returns a paginated list of playlists reposted by the authenticated user.
      tags: [Reposts]
      summary: List my reposted playlists
      operationId: getMyRepostedPlaylists
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated reposted playlists list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /me/reposted-albums:
    get:
      description: Returns a paginated list of albums reposted by the authenticated user.
      tags: [Reposts]
      summary: List my reposted albums
      operationId: getMyRepostedAlbums
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated reposted albums list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

# ============================================================
# COMPONENTS
# ============================================================
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Access token from /auth/login, /auth/verify-email, or OAuth endpoints.
        Expires in 15 minutes. Use /auth/refresh to renew.

  # ----------------------------------------------------------
  # Parameters
  # ----------------------------------------------------------
  parameters:
    UserId:
      name: user_id
      in: path
      required: true
      schema: { type: string, format: uuid }

    TrackId:
      name: track_id
      in: path
      required: true
      schema: { type: string, format: uuid }

    XCountryCode:
      name: X-Country-Code
      in: header
      required: false
      description: Optional infrastructure-injected ISO 3166-1 alpha-2 country code used for runtime geo playback restrictions.
      schema:
        type: string
        pattern: '^[A-Z]{2}$'
        example: EG

    QueueItemId:
      name: queue_item_id
      in: path
      required: true
      schema: { type: string, format: uuid }

    CommentId:
      name: comment_id
      in: path
      required: true
      schema: { type: string, format: uuid }

    PlaylistId:
      name: playlist_id
      in: path
      required: true
      schema: { type: string, format: uuid }

    Limit:
      name: limit
      in: query
      required: false
      schema: { type: integer, minimum: 1, maximum: 100, default: 20 }

    Offset:
      name: offset
      in: query
      required: false
      schema: { type: integer, minimum: 0, default: 0 }

  # ----------------------------------------------------------
  # Responses
  # ----------------------------------------------------------
  responses:
    ValidationError:
      description: Validation / bad request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: VALIDATION_FAILED
              message: Validation failed
              details:
                - field: email
                  issue: Invalid email format

    Unauthorized:
      description: Missing or invalid access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: AUTH_TOKEN_MISSING
              message: Authorization header missing

    Forbidden:
      description: Authenticated but not allowed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: PERMISSION_DENIED
              message: You do not have permission to perform this action.

    NotFound:
      description: Resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: RESOURCE_NOT_FOUND
              message: Resource not found.

    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: INTERNAL_SERVER_ERROR
              message: An unexpected error occurred

    TrackProcessingFailed:
      description: Track transcoding failed — cannot be played.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: UPLOAD_PROCESSING_FAILED
              message: Track processing failed

    FileTooLarge:
      description: Uploaded file exceeds the maximum allowed size.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: UPLOAD_FILE_TOO_LARGE
              message: File size exceeds the allowed limit

    UnsupportedMediaType:
      description: Uploaded file format not supported.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: UPLOAD_INVALID_FILE_TYPE
              message: Unsupported file format

    RateLimited:
      description: Too many requests.
      headers:
        Retry-After:
          schema: { type: integer }
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: RATE_LIMIT_EXCEEDED
              message: Too many requests

    UnprocessableEntity:
      description: Business rule validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: BUSINESS_RULE_VIOLATION
              message: CAPTCHA validation failed

  # ----------------------------------------------------------
  # Schemas
  # ----------------------------------------------------------
  schemas:
    # ── Shared error envelope ─────────────────────────────────
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'

    ErrorObject:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          example: VALIDATION_FAILED
        message:
          type: string
          example: Validation failed
        details:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/ErrorDetail'

    ErrorDetail:
      type: object
      required: [field, issue]
      properties:
        field:
          type: string
          example: email
        issue:
          type: string
          example: Invalid email format

    SuccessMessage:
      type: object
      required: [data, message]
      properties:
        data:
          type: object
          required: [success]
          properties:
            success:
              type: boolean
              example: true
        message:
          type: string
          example: Operation completed successfully.

    MessageResponse:
      type: object
      properties:
        message:
          type: string
          example: Operation completed.

    # ── Pagination — unified ListMeta (offset-based) ──────────
    # [FIX-6] Removed page-based Pagination schema.
    # All endpoints now use ListMeta.
    ListMeta:
      type: object
      description: Unified pagination envelope used by all list endpoints.
      required: [limit, offset, total]
      properties:
        limit:
          type: integer
          example: 20
        offset:
          type: integer
          example: 0
        total:
          type: integer
          description: Total matching records before pagination.
          example: 340

    # ── Shared user types ─────────────────────────────────────
    UserRole:
      type: string
      enum: [artist, listener, admin]

    GenderType:
      type: string
      enum: [male, female]

    UserSummary:
      type: object
      description: Minimal user info for list and feed responses.
      required: [user_id, email, display_name, role, is_verified]
      properties:
        user_id:
          type: string
          format: uuid
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        email:
          type: string
          format: email
          example: user@example.com
        display_name:
          type: string
          example: cairokee
        gender:
          allOf:
            - $ref: '#/components/schemas/GenderType'
          nullable: true
        role:
          $ref: '#/components/schemas/UserRole'
        is_verified:
          type: boolean
          example: true
        profile_picture:
          type: string
          format: uri
          nullable: true
          example: https://cdn.rythmify.com/avatars/user123.jpg

    PublicUser:
      type: object
      description: Public-facing user profile.
      required:
        [
          id,
          display_name,
          role,
          is_private,
          is_verified,
          followers_count,
          following_count,
          created_at,
        ]

      properties:
        id:
          type: string
          format: uuid
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        username:
          type: string
          nullable: true
          pattern: '^[a-z0-9_-]+$'
          example: soundwave_cairo
        display_name:
          type: string
          example: Soundwave
        bio:
          type: string
          nullable: true
        location:
          type: string
          nullable: true
        gender:
          allOf:
            - $ref: '#/components/schemas/GenderType'
          nullable: true
        role:
          $ref: '#/components/schemas/UserRole'
        profile_picture:
          type: string
          format: uri
          nullable: true
        cover_photo:
          type: string
          format: uri
          nullable: true
        is_private:
          type: boolean
          default: false
        is_verified:
          type: boolean
          default: false
        is_user_premium:
          type: boolean
          default: false
        followers_count:
          type: integer
          default: 0
        following_count:
          type: integer
          default: 0
        created_at:
          type: string
          format: date-time

    PublicUserResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/PublicUser'

    OwnUser:
      type: object
      description: Full authenticated user profile including all private fields.
      required:
        [
          id,
          email,
          display_name,
          role,
          is_private,
          is_verified,
          followers_count,
          following_count,
          created_at,
        ]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        username:
          type: string
          nullable: true
        display_name:
          type: string
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        bio:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        gender:
          allOf:
            - $ref: '#/components/schemas/GenderType'
          nullable: true
        role:
          $ref: '#/components/schemas/UserRole'
        profile_picture:
          type: string
          format: uri
          nullable: true
        cover_photo:
          type: string
          format: uri
          nullable: true
        is_private:
          type: boolean
        date_of_birth:
          type: string
          format: date
          nullable: true
        is_verified:
          type: boolean
        is_user_premium:
          type: boolean
        followers_count:
          type: integer
        following_count:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          nullable: true

    OwnProfileFullResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/OwnUser'
        message:
          type: string

    InsightMetrics:
      type: object
      required: [plays, likes, comments, reposts, downloads]
      properties:
        plays:
          type: integer
          minimum: 0
          example: 1200
        likes:
          type: integer
          minimum: 0
          example: 84
        comments:
          type: integer
          minimum: 0
          example: 19
        reposts:
          type: integer
          minimum: 0
          example: 12
        downloads:
          type: integer
          minimum: 0
          description: Currently zero until a downloads/offline-download event table exists.
          example: 0

    InsightSeriesPoint:
      allOf:
        - type: object
          required: [bucket]
          properties:
            bucket:
              type: string
              description: Date (`YYYY-MM-DD`) for daily ranges or month (`YYYY-MM`) for 12m.
              example: '2026-04-01'
        - $ref: '#/components/schemas/InsightMetrics'

    CreatorInsights:
      type: object
      required: [range, granularity, timezone, track_id, totals, series]
      properties:
        range:
          type: string
          enum: [7d, 30d, 12m]
          example: 30d
        granularity:
          type: string
          enum: [day, month]
          example: day
        timezone:
          type: string
          example: UTC
        track_id:
          type: string
          format: uuid
          nullable: true
        totals:
          $ref: '#/components/schemas/InsightMetrics'
        series:
          type: array
          items:
            $ref: '#/components/schemas/InsightSeriesPoint'

    CreatorInsightsResponse:
      type: object
      required: [data, message]
      properties:
        data:
          $ref: '#/components/schemas/CreatorInsights'
        message:
          type: string
          example: Insights fetched successfully.

    OwnProfileResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/OwnUser'
        message:
          type: string

    User:
      $ref: '#/components/schemas/OwnUser'

    WebProfile:
      type: object
      required: [id, platform, url]
      properties:
        id:
          type: string
          format: uuid
        platform:
          type: string
          enum: [instagram, twitter, youtube, tiktok, soundcloud, website, other]
        url:
          type: string
          format: uri

    # ── Auth schemas ──────────────────────────────────────────
    AuthRegisterRequest:
      type: object
      required: [email, password, display_name, captcha_token, gender, date_of_birth]
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          format: password
          minLength: 8
        display_name:
          type: string
          maxLength: 50
        gender:
          $ref: '#/components/schemas/GenderType'
        date_of_birth:
          type: string
          format: date
        captcha_token:
          type: string

    AuthRegisterResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required:
            [user_id, email, display_name, role, is_verified, created_at, gender, date_of_birth]
          properties:
            user_id:
              type: string
              format: uuid
            email:
              type: string
              format: email
            display_name:
              type: string
            gender:
              $ref: '#/components/schemas/GenderType'
            role:
              $ref: '#/components/schemas/UserRole'
            is_verified:
              type: boolean
              example: false
            date_of_birth:
              type: string
              format: date
            created_at:
              type: string
              format: date-time
        message:
          type: string
          example: Account created. Please verify your email.

    AuthVerifyEmailRequest:
      type: object
      required: [token]
      properties:
        token:
          type: string

    AccessTokenResponse:
      type: object
      required: [access_token, token_type, expires_in]
      properties:
        access_token:
          type: string
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          example: 900

    AuthVerifyEmailResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/AccessTokenResponse'
        message:
          type: string

    AuthResendVerificationRequest:
      type: object
      required: [email, captcha_token]
      properties:
        email:
          type: string
          format: email
        captcha_token:
          type: string

    AuthLoginRequest:
      type: object
      required: [identifier, password]
      properties:
        identifier:
          type: string
          description: Email address OR username.
        password:
          type: string
          format: password

    AuthLoginResponseData:
      type: object
      required: [access_token, token_type, expires_in, user, is_new_user]
      properties:
        access_token:
          type: string
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          example: 900
        user:
          $ref: '#/components/schemas/UserSummary'
        is_new_user:
          type: boolean
          example: false

    AuthLoginResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/AuthLoginResponseData'
        message:
          type: string
          example: Logged in successfully.

    AuthRefreshResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/AccessTokenResponse'
        message:
          type: string

    AuthForgotPasswordRequest:
      type: object
      required: [email]
      properties:
        email:
          type: string
          format: email

    AuthForgotPasswordResponse:
      type: object
      properties:
        message:
          type: string
          example: If the email exists, a password reset link has been sent.

    AuthResetPasswordRequest:
      type: object
      required: [token, new_password, confirm_password]
      properties:
        token:
          type: string
        new_password:
          type: string
          format: password
          minLength: 8
        confirm_password:
          type: string
          format: password
          minLength: 8
        logout_all:
          type: boolean
          default: true

    # [FIX-13]
    AuthChangePasswordRequest:
      type: object
      required: [current_password, new_password, confirm_password]
      properties:
        current_password:
          type: string
          format: password
          description: The user's existing password for verification.
        new_password:
          type: string
          format: password
          minLength: 8
          description: The new password to set.
        confirm_password:
          type: string
          format: password
          minLength: 8
          description: Must match new_password exactly.

    AuthChangeEmailRequest:
      type: object
      required: [new_email]
      properties:
        new_email:
          type: string
          format: email

    AuthVerifyEmailChangeRequest:
      type: object
      required: [token]
      properties:
        token:
          type: string

    AuthVerifyEmailChangeResponse:
      type: object
      required: [data, message]
      properties:
        data:
          type: object
          required: [email]
          properties:
            email:
              type: string
              format: email
        message:
          type: string

    AuthGoogleLoginRequest:
      type: object
      required: [id_token]
      properties:
        id_token:
          type: string

    AuthGoogleLoginResponseData:
      type: object
      required: [access_token, token_type, expires_in, is_new_user, user]
      properties:
        access_token:
          type: string
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          example: 900
        is_new_user:
          type: boolean
        user:
          $ref: '#/components/schemas/UserSummary'

    AuthGoogleLoginResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/AuthGoogleLoginResponseData'
        message:
          type: string

    CompleteGoogleOnboardingRequest:
      type: object
      required: [display_name, gender, date_of_birth]
      properties:
        display_name:
          type: string
          minLength: 1
          maxLength: 50
        gender:
          $ref: '#/components/schemas/GenderType'
        date_of_birth:
          type: string
          format: date
        bio:
          type: string
          nullable: true
          maxLength: 500
        location:
          type: string
          nullable: true
          maxLength: 100
      additionalProperties: false

    CompleteGoogleOnboardingResponse:
      type: object
      required: [data, message]
      properties:
        data:
          type: object
          required: [profile_completed, user]
          properties:
            profile_completed:
              type: boolean
            user:
              $ref: '#/components/schemas/OwnUser'
        message:
          type: string

    # ── User profile schemas ──────────────────────────────────
    UpdateProfileRequest:
      type: object
      properties:
        display_name:
          type: string
          minLength: 1
          maxLength: 50
        username:
          type: string
          pattern: '^[a-z0-9_-]+$'
          minLength: 3
          maxLength: 30
        first_name:
          type: string
          nullable: true
          maxLength: 50
        last_name:
          type: string
          nullable: true
          maxLength: 50
        bio:
          type: string
          nullable: true
          maxLength: 500
        city:
          type: string
          nullable: true
          maxLength: 100
        country:
          type: string
          nullable: true
          minLength: 2
          maxLength: 2
      additionalProperties: false

    UpdateAccountRequest:
      type: object
      properties:
        date_of_birth:
          type: string
          format: date
          nullable: true
        gender:
          $ref: '#/components/schemas/GenderType'
      additionalProperties: false

    SwitchRoleRequest:
      type: object
      required: [role]
      properties:
        role:
          type: string
          enum: [artist, listener]

    AvatarUploadRequest:
      type: object
      required: [avatar]
      properties:
        avatar:
          type: string
          format: binary

    CoverUploadRequest:
      type: object
      required: [cover]
      properties:
        cover:
          type: string
          format: binary

    AvatarUploadResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [profile_picture]
          properties:
            profile_picture:
              type: string
              format: uri
        message:
          type: string

    CoverUploadResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [cover_photo]
          properties:
            cover_photo:
              type: string
              format: uri
        message:
          type: string

    AddWebProfileRequest:
      type: object
      required: [platform, url]
      properties:
        platform:
          type: string
          enum: [instagram, twitter, youtube, tiktok, soundcloud, website, other]
        url:
          type: string
          format: uri

    WebProfileListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WebProfile'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    WebProfileCreatedResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/WebProfile'
        message:
          type: string

    UpdatePrivacyRequest:
      type: object
      required: [is_private]
      properties:
        is_private:
          type: boolean

    UpdatePrivacyResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [is_private]
          properties:
            is_private:
              type: boolean
        message:
          type: string

    ReplaceGenresRequest:
      type: object
      required: [genres]
      properties:
        genres:
          type: array
          maxItems: 10
          items:
            type: string

    GenresResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            type: object
            required: [id, name]
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
        pagination:
          $ref: '#/components/schemas/ListMeta'

    ContentSettings:
      type: object
      properties:
        rss_title:
          type: string
          nullable: true
        rss_language:
          type: string
        rss_category:
          type: string
          nullable: true
        rss_explicit:
          type: boolean
          default: false
        rss_show_email:
          type: boolean
          default: false
        default_include_in_rss:
          type: boolean
          default: true
        default_license_type:
          type: string
          enum: [all_rights_reserved, creative_commons]
          default: all_rights_reserved

    ContentSettingsResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/ContentSettings'

    UpdateContentSettingsRequest:
      type: object
      properties:
        rss_title:
          type: string
          nullable: true
          maxLength: 200
        rss_language:
          type: string
          nullable: true
        rss_category:
          type: string
          nullable: true
          maxLength: 100
        rss_explicit:
          type: boolean
          nullable: true
        rss_show_email:
          type: boolean
          nullable: true
        default_include_in_rss:
          type: boolean
          nullable: true
        default_license_type:
          type: string
          nullable: true
          enum: [all_rights_reserved, creative_commons]
      additionalProperties: false

    PrivacySettings:
      type: object
      properties:
        is_private:
          type: boolean
          default: false
        receive_messages_from_anyone:
          type: boolean
          default: true
        show_activities_in_discovery:
          type: boolean
          default: true
        show_as_top_fan:
          type: boolean
          default: true
        show_top_fans_on_tracks:
          type: boolean
          default: true

    PrivacySettingsResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/PrivacySettings'

    UpdatePrivacySettingsRequest:
      type: object
      properties:
        is_private:
          type: boolean
          nullable: true
        receive_messages_from_anyone:
          type: boolean
          nullable: true
        show_activities_in_discovery:
          type: boolean
          nullable: true
        show_as_top_fan:
          type: boolean
          nullable: true
        show_top_fans_on_tracks:
          type: boolean
          nullable: true
      additionalProperties: false

    FollowingSearchResult:
      type: object
      required: [id, display_name, is_verified]
      properties:
        id:
          type: string
          format: uuid
        display_name:
          type: string
        username:
          type: string
          nullable: true
        profile_picture:
          type: string
          format: uri
          nullable: true
        is_verified:
          type: boolean

    FollowingSearchResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [items, total, query]
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/FollowingSearchResult'
            total:
              type: integer
            query:
              type: string

    # ── Track schemas ─────────────────────────────────────────
    TrackStatus:
      type: string
      enum: [processing, ready, failed]

    Tag:
      type: object
      required: [id, name]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string

    TagListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    Genre:
      type: object
      required: [id, name]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          example: Pop

    GenreListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Genre'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    Track:
      type: object
      required:
        [
          id,
          title,
          status,
          is_public,
          user_id,
          artist_name,
          play_count,
          like_count,
          comment_count,
          repost_count,
          audio_url,
          created_at,
        ]

      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        description:
          type: string
          nullable: true
        genre:
          type: string
          nullable: true
        genre_name:
          type: string
          nullable: true
        tags:
          type: array
          items:
            type: string
          maxItems: 10
        duration:
          type: integer
          nullable: true
        file_size:
          type: integer
          nullable: true
        bitrate:
          type: integer
          nullable: true
        status:
          $ref: '#/components/schemas/TrackStatus'
        is_public:
          type: boolean
        is_hidden:
          type: boolean
          default: false
        user_id:
          type: string
          format: uuid
        artist_name:
          type: string
          description: Denormalised display_name of the track owner/uploader.
          example: DJ Karim
        play_count:
          type: integer
        like_count:
          type: integer
        comment_count:
          type: integer
        repost_count:
          type: integer
        is_liked_by_me:
          type: boolean
          description: True when the authenticated viewer has liked this track. Always false for anonymous viewers.
        is_reposted_by_me:
          type: boolean
          description: True when the authenticated viewer has reposted this track. Always false for anonymous viewers.
        is_artist_followed_by_me:
          type: boolean
          description: True when the authenticated viewer follows the track artist. Always false for anonymous viewers.
        audio_url:
          type: string
          format: uri
          nullable: true
          description: Original audio URL. Null when playback is region-restricted for the requester.
        stream_url:
          type: string
          format: uri
          nullable: true
          description: Stream URL. Null when playback is region-restricted for the requester.
        preview_url:
          type: string
          format: uri
          nullable: true
          description: Preview URL. Null when playback is region-restricted for the requester.
        waveform_url:
          type: string
          format: uri
          nullable: true
          description: Waveform asset URL. Null when playback is region-restricted for the requester.
        cover_image:
          type: string
          format: uri
          nullable: true
        artists:
          type: string
          nullable: true
        buy_link:
          type: string
          format: uri
          nullable: true
        record_label:
          type: string
          nullable: true
        publisher:
          type: string
          nullable: true
        release_date:
          type: string
          format: date
          nullable: true
        isrc:
          type: string
          nullable: true
        p_line:
          type: string
          nullable: true
        explicit_content:
          type: boolean
          default: false
        include_in_rss_feed:
          type: boolean
          default: true
        display_embed_code:
          type: boolean
          default: true
        enable_app_playback:
          type: boolean
          default: true
        enable_downloads:
          type: boolean
          default: false
        enable_offline_listening:
          type: boolean
          default: false
        license_type:
          type: string
          enum: [all_rights_reserved, creative_commons]
          default: all_rights_reserved
        allow_comments:
          type: boolean
          default: true
        show_comments_public:
          type: boolean
          default: true
        show_insights_public:
          type: boolean
          default: true
        geo_restriction_type:
          type: string
          enum: [worldwide, exclusive_regions, blocked_regions]
          default: worldwide
        geo_regions:
          type: array
          description: Valid ISO 3166-1 alpha-2 country codes where the geo restriction applies, for example EG or SA.
          items:
            type: string
            minLength: 2
            maxLength: 2
        is_geo_blocked:
          type: boolean
          description: True when playback/audio access is blocked for the request country.
        playback_restriction_reason:
          type: string
          nullable: true
          enum: [region_restricted]
          description: Present when playback URLs are masked by geo restriction.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          nullable: true

    TrackSummary:
      type: object
      description: Lightweight track for list responses (owned tracks, history).
      required: [id, title, user_id, artist_name]
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        genre:
          type: string
          nullable: true
        duration:
          type: integer
          nullable: true
        cover_image:
          type: string
          format: uri
          nullable: true
        user_id:
          type: string
          format: uuid
        artist_name:
          type: string
          description: Denormalised display_name of the track owner/uploader.
          example: DJ Karim
        play_count:
          type: integer
        like_count:
          type: integer
        comment_count:
          type: integer
        repost_count:
          type: integer
        stream_url:
          type: string
          format: uri
          nullable: true
          description: Null when playback is region-restricted for the requester.
        audio_url:
          type: string
          format: uri
          nullable: true
          description: Null when playback is region-restricted for the requester.
        is_geo_blocked:
          type: boolean
          description: True when playback/audio access is blocked for the request country.
        playback_restriction_reason:
          type: string
          nullable: true
          enum: [region_restricted]

    MyTrackSummary:
      allOf:
        - $ref: '#/components/schemas/TrackSummary'
        - type: object
          required: [is_liked_by_me]
          properties:
            is_liked_by_me:
              type: boolean
              description: True when the authenticated requester has liked this track.

    TrackResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/Track'

    MyTrackListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/MyTrackSummary'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    TrackListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TrackSummary'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    UploadTrackRequest:
      type: object
      required: [audio_file, title]
      properties:
        audio_file:
          type: string
          format: binary
        title:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type: string
          nullable: true
          maxLength: 2000
        genre:
          type: string
          nullable: true
          maxLength: 100
        tags:
          type: array
          maxItems: 10
          items:
            type: string
        is_public:
          type: boolean
          default: true
        cover_image:
          type: string
          format: binary
          nullable: true
        artists:
          type: string
          nullable: true
        buy_link:
          type: string
          format: uri
          nullable: true
        record_label:
          type: string
          nullable: true
          maxLength: 200
        publisher:
          type: string
          nullable: true
          maxLength: 200
        release_date:
          type: string
          format: date
          nullable: true
        isrc:
          type: string
          nullable: true
          maxLength: 12
        p_line:
          type: string
          nullable: true
          maxLength: 200
        explicit_content:
          type: boolean
          default: false
        include_in_rss_feed:
          type: boolean
          default: true
        display_embed_code:
          type: boolean
          default: true
        enable_app_playback:
          type: boolean
          default: true
        license_type:
          type: string
          enum: [all_rights_reserved, creative_commons]
          default: all_rights_reserved
        enable_downloads:
          type: boolean
          default: false
        enable_offline_listening:
          type: boolean
          default: false
        allow_comments:
          type: boolean
          default: true
        show_comments_public:
          type: boolean
          default: true
        show_insights_public:
          type: boolean
          default: true
        geo_restriction_type:
          type: string
          enum: [worldwide, exclusive_regions, blocked_regions]
          default: worldwide
        geo_regions:
          type: array
          description: Valid ISO 3166-1 alpha-2 country codes where the geo restriction applies, for example EG or SA.
          items:
            type: string
            minLength: 2
            maxLength: 2
          maxItems: 250

    UploadTrackResponse:
      type: object
      required: [data, message]
      properties:
        data:
          $ref: '#/components/schemas/Track'
        message:
          type: string
          example: Track uploaded successfully.

    UpdateTrackRequest:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type: string
          nullable: true
          maxLength: 2000
        genre:
          type: string
          nullable: true
          maxLength: 100
        tags:
          type: array
          maxItems: 10
          items:
            type: string
        artists:
          type: string
          nullable: true
        buy_link:
          type: string
          format: uri
          nullable: true
        record_label:
          type: string
          nullable: true
          maxLength: 200
        publisher:
          type: string
          nullable: true
          maxLength: 200
        release_date:
          type: string
          format: date
          nullable: true
        isrc:
          type: string
          nullable: true
          maxLength: 12
        p_line:
          type: string
          nullable: true
          maxLength: 200
        explicit_content:
          type: boolean
          nullable: true
        include_in_rss_feed:
          type: boolean
          nullable: true
        display_embed_code:
          type: boolean
          nullable: true
        enable_app_playback:
          type: boolean
          nullable: true
        license_type:
          type: string
          nullable: true
          enum: [all_rights_reserved, creative_commons]
        enable_downloads:
          type: boolean
          nullable: true
        enable_offline_listening:
          type: boolean
          nullable: true
        allow_comments:
          type: boolean
          nullable: true
        show_comments_public:
          type: boolean
          nullable: true
        show_insights_public:
          type: boolean
          nullable: true
        geo_restriction_type:
          type: string
          nullable: true
          enum: [worldwide, exclusive_regions, blocked_regions]
        geo_regions:
          type: array
          nullable: true
          description: Valid ISO 3166-1 alpha-2 country codes where the geo restriction applies, for example EG or SA.
          items:
            type: string
            minLength: 2
            maxLength: 2
          maxItems: 250

    UpdateTrackCoverImageRequest:
      type: object
      required: [cover_image]
      properties:
        cover_image:
          type: string
          format: binary

    UpdateTrackAudioRequest:
      type: object
      required: [audio_file]
      properties:
        audio_file:
          type: string
          format: binary

    UpdateTrackVisibilityRequest:
      type: object
      required: [is_public]
      properties:
        is_public:
          type: boolean

    UpdateTrackVisibilityResponse:
      type: object
      required: [data, message]
      properties:
        data:
          type: object
          required: [track_id, is_public]
          properties:
            track_id:
              type: string
              format: uuid
            is_public:
              type: boolean
        message:
          type: string

    TrackStreamResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [track_id, stream_url]
          properties:
            track_id:
              type: string
              format: uuid
            stream_url:
              type: string
              format: uri

    TrackOfflineDownloadResponse:
      type: object
      required: [data, message]
      properties:
        data:
          type: object
          required: [track_id, download_url, source, expires_in_seconds, expires_at]
          properties:
            track_id:
              type: string
              format: uuid
            download_url:
              type: string
              format: uri
            source:
              type: string
              enum: [stream, audio]
            expires_in_seconds:
              type: integer
              example: 300
            expires_at:
              type: string
              format: date-time
        message:
          type: string

    TrackWaveformResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [track_id, peaks]
          properties:
            track_id:
              type: string
              format: uuid
            peaks:
              type: array
              items:
                type: number
                format: float
                minimum: 0.0
                maximum: 1.0

    PrivateShareLinkData:
      type: object
      required: [track_id, secret_token, share_url]
      properties:
        track_id:
          type: string
          format: uuid
        secret_token:
          type: string
        share_url:
          type: string
          example: http://localhost:5173/tracks/track-1?secret_token=secret-123

    PrivateShareLinkResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/PrivateShareLinkData'
        message:
          type: string
          example: Private share link fetched successfully.

    TrackLeaderboardUser:
      type: object
      description: Lightweight user info for track leaderboard cards.
      required: [id, display_name, is_verified]
      properties:
        id:
          type: string
          format: uuid
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        username:
          type: string
          nullable: true
          pattern: '^[a-z0-9_-]+$'
          example: soundwave_cairo
        display_name:
          type: string
          example: Soundwave
        profile_picture:
          type: string
          format: uri
          nullable: true
          example: https://cdn.rythmify.com/avatars/user123.jpg
        is_verified:
          type: boolean
          default: false

    FanLeaderboardEntry:
      type: object
      required: [rank, user, play_count]
      properties:
        rank:
          type: integer
          example: 1
        user:
          $ref: '#/components/schemas/TrackLeaderboardUser'
        play_count:
          type: integer
          example: 37
        last_played_at:
          type: string
          format: date-time
          nullable: true
          example: '2026-04-09T08:30:00Z'

    FanLeaderboardResponse:
      type: object
      required: [data, message]
      properties:
        data:
          type: object
          required: [period, items]
          properties:
            period:
              type: string
              enum: [overall, first_7_days]
              example: overall
              description: |
                `overall` means all-time plays.
                `first_7_days` means the fixed first 7 days from the track release window, not a rolling recent 7-day window.
            items:
              type: array
              maxItems: 5
              items:
                $ref: '#/components/schemas/FanLeaderboardEntry'
              example:
                - rank: 1
                  user:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    username: soundwave_cairo
                    display_name: Soundwave
                    profile_picture: https://cdn.rythmify.com/avatars/user123.jpg
                    is_verified: true
                  play_count: 37
                  last_played_at: '2026-04-09T08:30:00Z'
        message:
          type: string
          example: Fan leaderboard fetched successfully.

    # ── Playback schemas ──────────────────────────────────────
    PlaybackAccessLevel:
      type: string
      enum: [full, preview, blocked]

    PlaybackBlockReason:
      type: string
      enum:
        - region_restricted
        - PERMISSION_FEATURE_RESTRICTED
        - AUTH_ACCOUNT_SUSPENDED
        - RESOURCE_PRIVATE
        - REGION_BLOCKED
        - CONTENT_MODERATED

    RecordPlayResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [track_id, state, stream_url, preview_url, reason]
          properties:
            track_id:
              type: string
              format: uuid
            state:
              type: string
              enum: [playable, preview]
            stream_url:
              type: string
              format: uri
              nullable: true
            preview_url:
              type: string
              format: uri
              nullable: true
            reason:
              type: string
              nullable: true

    PlaybackStateResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [track_id, state, stream_url, preview_url, reason]
          properties:
            track_id:
              type: string
              format: uuid
            state:
              type: string
              enum: [playable, preview, blocked, processing, failed, unavailable]
            stream_url:
              type: string
              format: uri
              nullable: true
            preview_url:
              type: string
              format: uri
              nullable: true
            reason:
              allOf:
                - $ref: '#/components/schemas/PlaybackBlockReason'
              nullable: true
              description: Uses `region_restricted` when geo restriction blocks playback.

    QueueBucketEnum:
      type: string
      enum: [next_up, context]
      description: |
        Identifies which playback bucket a queue item belongs to.
        This field controls queue placement and ordering, not provenance.
        `next_up` is the user-prioritized bucket that plays before the passive context.
        `context` is the passive playback bucket behind the current item and any `next_up`
        items.

    QueueSourceTypeEnum:
      type: string
      enum:
        [
          track,
          playlist,
          album,
          mix,
          station,
          genre,
          liked_tracks,
          listening_history,
          reposts,
          user_tracks,
          system,
        ]
      description: |
        Describes where a queue item came from.
        This field is provenance metadata, not queue placement.
        `track` means an individually queued track.
        Context items may come from playlists, albums, mixes, stations, genres,
        liked tracks, listening history, reposts, or user uploads.
        User-scoped context items store the effective user id in `source_id`.
        A context inserted into `queue_bucket=next_up` still keeps its original
        `source_type` such as `genre` or `playlist`.
        `system` is reserved for legacy or system-managed queue sources.

    QueueContextInteractionTypeEnum:
      type: string
      enum: [play, next_up]
      description: |
        Controls how the resolved context is applied.
        `play` starts the resolved context immediately, sets the current track to the
        first resolved track, preserves the existing `next_up` bucket, and replaces the
        old `context` bucket.
        `next_up` preserves the current track, appends the resolved items to the end of
        the `next_up` bucket, and leaves the existing `context` bucket behind them.

    QueueContextSourceTypeEnum:
      type: string
      enum:
        [
          track,
          playlist,
          album,
          mix,
          station,
          genre,
          liked_tracks,
          listening_history,
          reposts,
          user_tracks,
        ]
      description: |
        Allowed resolver source types for `POST /me/player/queue/context`.
        - `track`: queue one direct track into `next_up` by `source_id`. This source
          type only supports `interaction_type=next_up`.
        - `playlist`: resolve tracks from a playlist by `source_id`.
        - `album`: resolve tracks from an album by `source_id`.
        - `mix`: resolve tracks from a mix by `source_id`. Mix ids may be non-UUID
          strings.
        - `station`: resolve tracks from a station by `source_id`.
        - `genre`: resolve tracks from a genre by `source_id`.
        - `liked_tracks`: resolve a user's liked tracks. Uses `target_user_id` when
          provided and otherwise defaults to the authenticated user.
        - `listening_history`: resolve the authenticated user's listening history.
          This source is self-only.
        - `reposts`: resolve a user's reposted tracks. Uses `target_user_id` when
          provided and otherwise defaults to the authenticated user.
        - `user_tracks`: resolve tracks uploaded by a user. Uses `target_user_id` when
          provided and otherwise defaults to the authenticated user.

    LegacyQueueTrackId:
      type: string
      format: uuid
      description: Legacy queue input format accepted for backward compatibility.

    QueueItemInput:
      type: object
      required: [track_id]
      properties:
        queue_item_id:
          type: string
          format: uuid
          description: Optional stable identifier for this queue occurrence as a UUID-formatted string. Generated when omitted.
        track_id:
          type: string
          format: uuid
          description: Track identifier as a UUID-formatted string.
        queue_bucket:
          allOf:
            - $ref: '#/components/schemas/QueueBucketEnum'
          default: next_up
          description: |
            Playback bucket where this queue item should live.
            Use `next_up` versus `context` for ordering and grouping, not for source
            provenance.
        source_type:
          allOf:
            - $ref: '#/components/schemas/QueueSourceTypeEnum'
          default: track
          description: |
            Provenance for this queue item.
            This describes the resolved source context such as `playlist`, `genre`, or
            `liked_tracks`; it does not describe queue placement.
        source_id:
          type: string
          nullable: true
          description: |
            Source identifier used to resolve the queue item.
            This may be a UUID, a user id, a mix key, or `null` for direct track queueing.
            For user-scoped contexts in responses, this stores the effective user id.
        source_title:
          type: string
          nullable: true
          description: |
            Human-readable source label for FE display.
            Combine this with `source_type` when rendering provenance badges or subtitles.
        source_position:
          type: integer
          minimum: 0
          nullable: true
          description: |
            Order of this item inside the resolved source context when that ordering is
            meaningful.
            Use this for provenance display, not for overall queue placement.
        added_at:
          type: string
          format: date-time
          description: Optional timestamp for when the queue item was created. Generated when omitted.
      example:
        queue_item_id: e85d14f1-98eb-462d-b3f0-4f7f78cc8c7c
        track_id: 91d42a97-cb47-429e-b9e3-88fbff4e2680
        queue_bucket: context
        source_type: playlist
        source_id: 4b28f3dd-2875-4811-aaf1-4fda7d3d113c
        source_title: My Running Mix
        source_position: 5
        added_at: '2026-04-18T20:00:19.000Z'

    QueueInputItem:
      oneOf:
        - $ref: '#/components/schemas/LegacyQueueTrackId'
        - $ref: '#/components/schemas/QueueItemInput'
      description: Accepts either a legacy track UUID or a rich queue-item object.

    QueueItem:
      type: object
      required:
        [
          queue_item_id,
          track_id,
          queue_bucket,
          source_type,
          source_id,
          source_title,
          source_position,
          added_at,
          stream_url,
          track_title,
          artist_name,
          duration,
          cover_image,
        ]
      properties:
        queue_item_id:
          type: string
          format: uuid
          description: Queue item occurrence identifier as a UUID-formatted string.
        track_id:
          type: string
          format: uuid
          description: Track identifier as a UUID-formatted string.
        queue_bucket:
          allOf:
            - $ref: '#/components/schemas/QueueBucketEnum'
          description: |
            Playback bucket where this queue item now lives.
            Use this field for playback ordering and queue UI grouping.
        source_type:
          allOf:
            - $ref: '#/components/schemas/QueueSourceTypeEnum'
          description: |
            Provenance of the returned queue item.
            This is not the same as `queue_bucket`; a `playlist` or `genre` item can
            still live in `queue_bucket=next_up`.
        source_id:
          type: string
          nullable: true
          description: |
            Identifier for the resolved source represented by this queue item.
            This may be a playlist id, album id, mix key, genre id, station id, effective
            user id, or `null` for direct track queueing.
        source_title:
          type: string
          nullable: true
          description: |
            Human-readable source label for FE rendering.
            Use this together with `source_type` when showing provenance to users.
        source_position:
          type: integer
          minimum: 0
          nullable: true
          description: |
            Order of this item inside the resolved source context when relevant.
            This does not indicate whether the item is in `next_up` or `context`.
        added_at:
          type: string
          format: date-time
        stream_url:
          type: string
          nullable: true
          description: Playable stream URL derived from the queued track id when the track still exists.
        track_title:
          type: string
          nullable: true
          description: Convenience track title derived from `track_id`.
        artist_name:
          type: string
          nullable: true
          description: Convenience artist display name derived from `track_id`.
        duration:
          type: integer
          nullable: true
          description: Convenience duration derived from `track_id`.
        cover_image:
          type: string
          nullable: true
          description: Convenience cover image URL derived from track_id.
      example:
        queue_item_id: e85d14f1-98eb-462d-b3f0-4f7f78cc8c7c
        track_id: 91d42a97-cb47-429e-b9e3-88fbff4e2680
        queue_bucket: context
        source_type: playlist
        source_id: 4b28f3dd-2875-4811-aaf1-4fda7d3d113c
        source_title: My Running Mix
        source_position: 5
        added_at: '2026-04-18T20:00:19.000Z'
        stream_url: https://cdn.rythmify.app/tracks/91d42a97-cb47-429e-b9e3-88fbff4e2680/stream.mp3
        track_title: Runaway Pulse
        artist_name: Echo Atlas
        duration: 219
        cover_image: https://cdn.rythmify.app/covers/example.jpg

    SavePlayerStateRequest:
      type: object
      required: [track_id, position_seconds]
      properties:
        track_id:
          type: string
          format: uuid
          description: Current track as a UUID-formatted string.
        position_seconds:
          type: number
          format: float
          minimum: 0
        volume:
          type: number
          format: float
          minimum: 0.0
          maximum: 1.0
        queue:
          type: array
          description: Ordered upcoming queue. Accepts legacy track UUIDs or queue-item objects.
          items:
            $ref: '#/components/schemas/QueueInputItem'

    PlayerState:
      type: object
      required:
        [
          track_id,
          track_title,
          artist_name,
          stream_url,
          duration,
          cover_image,
          position_seconds,
          volume,
          queue,
          saved_at,
        ]
      properties:
        track_id:
          type: string
          format: uuid
          nullable: true
          description: |
            Currently playing track. May be `null` when only queued items exist and playback
            has not started yet.
        track_title:
          type: string
          nullable: true
          description: Convenience title derived from the current `track_id`.
        artist_name:
          type: string
          nullable: true
          description: Convenience artist display name derived from the current `track_id`.
        stream_url:
          type: string
          nullable: true
          description: Playable stream URL derived from the current `track_id` when the track still exists.
        duration:
          type: integer
          nullable: true
          description: Convenience duration derived from the current `track_id`.
        cover_image:
          type: string
          nullable: true
          description: Convenience cover image URL derived from the current track_id.
        position_seconds:
          type: number
          format: float
        volume:
          type: number
          format: float
        queue:
          type: array
          items:
            $ref: '#/components/schemas/QueueItem'
        saved_at:
          type: string
          format: date-time

    PlayerStateResponse:
      type: object
      required: [data]
      properties:
        data:
          allOf:
            - $ref: '#/components/schemas/PlayerState'
          nullable: true

    PlayerQueue:
      type: object
      required: [queue]
      properties:
        queue:
          type: array
          items:
            $ref: '#/components/schemas/QueueItem'

    PlayerQueueResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/PlayerQueue'

    QueueReorderInstruction:
      type: object
      required: [queue_item_id, position]
      description: One queue item placement instruction keyed by queue_item_id.
      properties:
        queue_item_id:
          type: string
          format: uuid
          description: Queue item occurrence identifier as a UUID-formatted string. Use queue_item_id, not track_id.
        position:
          type: integer
          minimum: 1
          description: 1-based target position in the full reordered queue.

    QueueReorderRequest:
      type: object
      required: [items]
      description: Full queue permutation request. items must include every current queue item exactly once.
      properties:
        items:
          type: array
          minItems: 1
          description: Every current queue item exactly once, with unique contiguous positions from 1..N.
          items:
            $ref: '#/components/schemas/QueueReorderInstruction'

    QueueContextRequest:
      type: object
      required: [interaction_type, source_type]
      properties:
        interaction_type:
          allOf:
            - $ref: '#/components/schemas/QueueContextInteractionTypeEnum'
          description: |
            Controls how the resolved context is applied to the current player state.
            Use `play` to start the resolved context immediately and replace the existing
            `context` bucket while preserving `next_up`.
            Use `next_up` to append the resolved items to the end of the `next_up`
            bucket while leaving the current track and existing `context` bucket in
            place.
        source_type:
          allOf:
            - $ref: '#/components/schemas/QueueContextSourceTypeEnum'
          description: |
            Selects which supported resolver should be used.
            This field identifies where tracks should be resolved from, such as a
            `track`, `playlist`, `mix`, `liked_tracks`, or `user_tracks`.
        source_id:
          type: string
          nullable: true
          description: |
            Source identifier for non-user-scoped contexts.
            Required for `track`, `playlist`, `album`, `mix`, `station`, and `genre`.
            Usually omitted or `null` for `liked_tracks`, `listening_history`,
            `reposts`, and `user_tracks`.
            For `source_type=track`, `playlist`, `album`, `station`, and `genre`, use a
            UUID-formatted string.
            Do not assume this field is always a UUID because `mix` may use string ids.
        target_user_id:
          type: string
          format: uuid
          nullable: true
          description: |
            Effective user scope for user-scoped source types.
            Optional for `liked_tracks`, `reposts`, and `user_tracks`; defaults to the
            authenticated user when omitted. Use a UUID-formatted string when provided.
            Should be omitted or `null` for `track`, `playlist`, `album`, `mix`,
            `station`, and `genre`.
            `listening_history` is self-only, so requesting another user's history
            through this endpoint is not allowed.
      example:
        interaction_type: play
        source_type: playlist
        source_id: 4b28f3dd-2875-4811-aaf1-4fda7d3d113c
        target_user_id: null
    # Playback sync schemas
    PlaybackSyncHistoryEventRequest:
      type: object
      required: [track_id, played_at]
      properties:
        track_id:
          type: string
          format: uuid
          description: UUID-formatted string of the track that was played.
          example: e5f6a7b8-c9d0-1234-efab-567890abcdef
        played_at:
          type: string
          format: date-time
          description: |
            Timestamp when the play occurred. Can be in the past for offline sync.
            Must not be more than 7 days in the past.
          example: '2026-04-03T10:45:00Z'
        duration_played_seconds:
          type: integer
          minimum: 0
          description: How many seconds of the track were played. Used for analytics.
          example: 180

    PlaybackSyncCurrentStateRequest:
      type: object
      required: [track_id, position_seconds, state_updated_at]
      properties:
        track_id:
          type: string
          format: uuid
          description: Current track as a UUID-formatted string.
        position_seconds:
          type: number
          format: float
          minimum: 0
        volume:
          type: number
          format: float
          minimum: 0.0
          maximum: 1.0
        queue:
          type: array
          description: Ordered upcoming queue. Accepts legacy track UUID-formatted strings or queue-item objects.
          items:
            $ref: '#/components/schemas/QueueInputItem'
        state_updated_at:
          type: string
          format: date-time
          description: Timestamp when the client last updated this player state.

    PlaybackSyncRequest:
      type: object
      description: At least one of history_events or current_state must be provided.
      properties:
        history_events:
          type: array
          items:
            $ref: '#/components/schemas/PlaybackSyncHistoryEventRequest'
        current_state:
          $ref: '#/components/schemas/PlaybackSyncCurrentStateRequest'

    PlaybackSyncResult:
      type: object
      required:
        [
          history_events_received,
          history_events_recorded,
          history_events_deduplicated,
          current_state_saved,
          current_state_ignored_as_stale,
        ]
      properties:
        history_events_received:
          type: integer
          minimum: 0
        history_events_recorded:
          type: integer
          minimum: 0
        history_events_deduplicated:
          type: integer
          minimum: 0
        current_state_saved:
          type: boolean
        current_state_ignored_as_stale:
          type: boolean
        current_state:
          allOf:
            - $ref: '#/components/schemas/PlayerState'
          nullable: true

    PlaybackSyncResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/PlaybackSyncResult'

    ListeningHistoryEntry:
      type: object
      required: [id, track, played_at]
      properties:
        id:
          type: string
          format: uuid
        track:
          $ref: '#/components/schemas/TrackSummary'
        played_at:
          type: string
          format: date-time

    RecentlyPlayedTrackSummary:
      allOf:
        - $ref: '#/components/schemas/TrackSummary'
        - type: object
          required: [tags, is_liked_by_me, is_reposted_by_me, is_artist_followed_by_me]
          properties:
            tags:
              type: array
              maxItems: 10
              items:
                type: string
              example: [house, summer]
            is_liked_by_me:
              type: boolean
              description: True when the authenticated requester has liked this track.
            is_reposted_by_me:
              type: boolean
              description: True when the authenticated requester has reposted this track.
            is_artist_followed_by_me:
              type: boolean
              description: True when the authenticated requester follows the track artist.

    RecentlyPlayedEntry:
      type: object
      required: [track, last_played_at]
      properties:
        track:
          $ref: '#/components/schemas/RecentlyPlayedTrackSummary'
        last_played_at:
          type: string
          format: date-time

    RecentlyPlayedResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/RecentlyPlayedEntry'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    ListeningHistoryResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ListeningHistoryEntry'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    # ── Playlist schemas ──────────────────────────────────────
    CreatePlaylistRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        description:
          type: string
          maxLength: 500
          nullable: true
        is_public:
          type: boolean
          default: true

    PlaylistOwnerSummary:
      type: object
      required: [id, display_name]
      properties:
        id:
          type: string
          format: uuid
        display_name:
          type: string

    PlaylistTrackItem:
      type: object
      required: [track_id, position, added_at]
      properties:
        track_id:
          type: string
          format: uuid
        position:
          type: integer
          minimum: 1
        added_at:
          type: string
          format: date-time

    Playlist:
      type: object
      required: [playlist_id, owner_user_id, name, is_public, created_at]
      properties:
        playlist_id:
          type: string
          format: uuid
        owner_user_id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
          nullable: true
        is_public:
          type: boolean
        created_at:
          type: string
          format: date-time
        track_count:
          type: integer
        like_count:
          type: integer
        cover_image:
          type: string
          format: uri
          nullable: true
        # [FIX-10] Changed from $ref Track to $ref DiscoveryTrack
        preview_track:
          allOf:
            - $ref: '#/components/schemas/DiscoveryTrack'
          nullable: true
          description: |
            First track of the playlist for instant playback from Home screen.
            null if playlist is empty.

    PlaylistDetails:
      allOf:
        - $ref: '#/components/schemas/Playlist'
        - type: object
          properties:
            tracks:
              type: array
              items:
                $ref: '#/components/schemas/PlaylistTrackItem'

    PlaylistResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/Playlist'
        message:
          type: string

    PlaylistGetResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/PlaylistDetails'
        message:
          type: string

    PlaylistTracksGetResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [playlist_id, tracks, pagination]
          properties:
            playlist_id:
              type: string
              format: uuid
            tracks:
              type: array
              items:
                type: object
                required: [track_id, position, added_at]
                properties:
                  track_id:
                    type: string
                    format: uuid
                  position:
                    type: integer
                    minimum: 1
                  added_at:
                    type: string
                    format: date-time
                  title:
                    type: string
                  duration:
                    type: integer
                    nullable: true
                  cover_image:
                    type: string
                    format: uri
                    nullable: true
                  is_public:
                    type: boolean
                  deleted_at:
                    type: string
                    format: date-time
                    nullable: true
                  artist_name:
                    type: string
                    nullable: true
                  artist_id:
                    type: string
                    format: uuid
            pagination:
              type: object
              required: [page, per_page, total_items, total_pages, has_next, has_prev]
              properties:
                page:
                  type: integer
                  minimum: 1
                per_page:
                  type: integer
                  minimum: 1
                total_items:
                  type: integer
                  minimum: 0
                total_pages:
                  type: integer
                  minimum: 0
                has_next:
                  type: boolean
                has_prev:
                  type: boolean
        message:
          type: string

    PlaylistListResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [items, meta]
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/Playlist'
            meta:
              $ref: '#/components/schemas/ListMeta'
        message:
          type: string

    UpdatePlaylistRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        description:
          type: string
          maxLength: 500
          nullable: true
        is_public:
          type: boolean
      additionalProperties: false

    AddTrackToPlaylistRequest:
      type: object
      required: [track_id]
      properties:
        track_id:
          type: string
          format: uuid
        position:
          type: integer
          minimum: 1
          nullable: true
      additionalProperties: false

    ReorderPlaylistTracksRequest:
      type: object
      required: [items]
      properties:
        items:
          type: array
          minItems: 1
          items:
            type: object
            required: [track_id, position]
            properties:
              track_id:
                type: string
                format: uuid
              position:
                type: integer
                minimum: 1

    PlaylistEmbedResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [embed_url, iframe_html]
          properties:
            embed_url:
              type: string
              format: uri
            iframe_html:
              type: string
        message:
          type: string

    PlaylistSummary:
      type: object
      description: Minimal playlist info for search results.
      required: [id, title, owner]
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        owner:
          $ref: '#/components/schemas/PlaylistOwnerSummary'
        track_count:
          type: integer
        created_at:
          type: string
          format: date-time

    # ── Discovery track model (lightweight, used across all discovery) ──
    # [FIX-8] Added repost_count
    DiscoveryTrack:
      type: object
      description: |
        Lightweight track object used across all discovery, feed, and search endpoints.
        artist_name is denormalised to avoid per-item user lookups.
        Use this schema (not Track or FeedTrack) anywhere a compact track is needed.
      required: [id, title, user_id, play_count, is_liked_by_me]
      properties:
        id:
          type: string
          format: uuid
          example: e5f6a7b8-c9d0-1234-efab-567890abcdef
        title:
          type: string
          example: Summer Vibes
        cover_image:
          type: string
          format: uri
          nullable: true
          example: https://cdn.rythmify.com/covers/track1.jpg
        duration:
          type: integer
          nullable: true
          description: Duration in seconds.
          example: 213
        genre_name:
          type: string
          nullable: true
          example: Electronic
        play_count:
          type: integer
          example: 4200
        like_count:
          type: integer
          example: 312
        # [FIX-8] Added
        repost_count:
          type: integer
          nullable: true
          example: 47
        user_id:
          type: string
          format: uuid
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        artist_name:
          type: string
          nullable: true
          description: Denormalised display_name of the track owner.
          example: DJ Karim
        stream_url:
          type: string
          format: uri
          nullable: true
          example: https://cdn.rythmify.com/tracks/e5f6a7b8/stream.mp3
        preview_url:
          type: string
          format: uri
          nullable: true
          example: https://cdn.rythmify.com/tracks/e5f6a7b8/preview.mp3
        created_at:
          type: string
          format: date-time
          example: '2026-03-01T10:00:00Z'
        is_liked_by_me:
          type: boolean
          description: Whether the authenticated viewer has liked this track.
          example: false

    # [FIX-1][FIX-3][FIX-14] Unified feed item schema replacing FeedTrack in feed endpoints.
    # FeedTrack is kept below for search/trending use but aligned to DiscoveryTrack field names.
    FeedItem:
      type: object
      description: |
        A single item in the Following or Discover feed.
        item_type distinguishes original posts from reposts.
        When item_type = "repost", repost_by is the user who reposted it.
      required: [item_type, track]
      properties:
        item_type:
          type: string
          enum: [track, repost]
          description: |
            track — original upload by a followed user.
            repost — a track reposted by a followed user.
          example: repost
        repost_by:
          nullable: true
          description: |
            The user who performed the repost. Present only when item_type = "repost".
            null when item_type = "track".
          allOf:
            - $ref: '#/components/schemas/RepostByUser'
        reposted_at:
          type: string
          format: date-time
          nullable: true
          description: When the repost occurred. Present only when item_type = "repost".
          example: '2026-04-03T09:15:00Z'
        track:
          $ref: '#/components/schemas/DiscoveryTrack'

    RepostByUser:
      type: object
      description: Minimal user info for the user who performed a repost.
      required: [id, display_name]
      properties:
        id:
          type: string
          format: uuid
          example: b2c3d4e5-f6a7-8901-bcde-f12345678901
        display_name:
          type: string
          example: Ahmed Sami
        username:
          type: string
          nullable: true
          example: ahmed_sami
        profile_picture:
          type: string
          format: uri
          nullable: true
          example: https://cdn.rythmify.com/avatars/ahmed.jpg

    # Cursor-based feed response — used by GET /feed and GET /feed/discovery
    # Controllers return { data, hasMore, nextCursor, message } — NOT offset-based pagination
    CursorFeedResponse:
      type: object
      description: Cursor-paginated response for GET /feed and GET /feed/discovery.
      required: [data, hasMore]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FeedItem'
        hasMore:
          type: boolean
          description: Whether more items are available after this page.
        nextCursor:
          type: string
          nullable: true
          description: Opaque cursor to pass as `cursor` param to fetch the next page. Null when no more pages.
        message:
          type: string
          example: Activity feed fetched successfully.

    # Legacy alias kept for /feed/trending (UNVERIFIED — route does not exist in code)
    FeedResponse:
      type: object
      description: Offset-paginated feed response. Only referenced by the UNVERIFIED /feed/trending path.
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FeedItem'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    # [FIX-14] FeedTrack aligned with DiscoveryTrack field names (cover_image, flat artist_name)
    # Still used by /feed/trending and /search
    FeedTrack:
      type: object
      description: |
        Track with artist summary. Used in trending feed and search results.
        Field names are aligned with DiscoveryTrack (cover_image, artist_name).
      required: [id, title, artist_name, user_id]
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        # [FIX-14] Was cover_url — now cover_image (aligned with DiscoveryTrack)
        cover_image:
          type: string
          format: uri
          nullable: true
        # [FIX-14] Was artist.display_name nested object — now flat artist_name string
        artist_name:
          type: string
          nullable: true
          description: Denormalised display_name of the track owner.
        user_id:
          type: string
          format: uuid
        genre_name:
          type: string
          nullable: true
        duration:
          type: integer
          nullable: true
        play_count:
          type: integer
        like_count:
          type: integer
        repost_count:
          type: integer
          nullable: true
        stream_url:
          type: string
          format: uri
          nullable: true
        created_at:
          type: string
          format: date-time

    TrendingTrack:
      allOf:
        - $ref: '#/components/schemas/FeedTrack'
        - type: object
          properties:
            rank:
              type: integer
              description: Position in trending chart (1-based).
              example: 1
            trend_score:
              type: number
              format: float
              description: Normalised trending score (0–1).
              example: 0.94

    TrendingFeedResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TrendingTrack'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    # [FIX-6][FIX-7] Search response — pagination inside data, per-type metadata
    SearchResponse:
      type: object
      required: [data, pagination]
      description: |
        Paginated search results.

        When `type=everything`, `data` is a flat array of mixed resource items.
        When a specific `type` is provided, only that resource's array is populated.
        When no `type` is given, all arrays are populated with top results.

        `filters` is null when no type is specified.
      properties:
        data:
          type: object
          required: [tracks, users, playlists, albums]
          properties:
            tracks:
              type: array
              items:
                $ref: '#/components/schemas/TrackSearchResult'
            users:
              type: array
              items:
                $ref: '#/components/schemas/UserSearchResult'
            playlists:
              type: array
              items:
                $ref: '#/components/schemas/PlaylistSearchResult'
            albums:
              type: array
              items:
                $ref: '#/components/schemas/AlbumSearchResult'
        pagination:
          $ref: '#/components/schemas/ListMeta'
        filters:
          nullable: true
          description: Active filter metadata for the current type. Null when no type is specified.
          type: object
          properties:
            time_range:
              type: string
              enum: [past_hour, past_day, past_week, past_month, past_year]
              nullable: true
            duration:
              type: string
              enum: [short, medium, long, extra]
              nullable: true
            tag:
              type: string
              nullable: true
            location:
              type: string
              nullable: true

    TrackSearchResult:
      allOf:
        - $ref: '#/components/schemas/FeedTrack'
        - type: object
          properties:
            score:
              type: number
              format: float
              example: 0.92

    UserSearchResult:
      type: object
      required: [id, display_name]
      properties:
        id:
          type: string
          format: uuid
        display_name:
          type: string
        profile_picture:
          type: string
          format: uri
          nullable: true
        follower_count:
          type: integer
        score:
          type: number
          format: float
          example: 0.75

    PlaylistSearchResult:
      allOf:
        - $ref: '#/components/schemas/PlaylistSummary'
        - type: object
          properties:
            score:
              type: number
              format: float
              example: 0.81
    AlbumSearchResult:
      type: object
      required: [id, title, artist]
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        cover_image:
          type: string
          format: uri
          nullable: true
        artist:
          $ref: '#/components/schemas/UserSummary'
        track_count:
          type: integer
        score:
          type: number
          format: float
          example: 0.78

    SearchSuggestionsResponse:
      type: object
      required: [data]
      properties:
        data:
          type: array
          items:
            type: string
          example: ['lofi hip hop', 'lofi beats', 'lofi chill']

    ResolveResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [type, id, permalink]
          properties:
            type:
              type: string
              enum: [track, user, playlist, album]
            id:
              type: string
              format: uuid
            permalink:
              type: string
              format: uri

    # ── Discovery & Genre schemas ─────────────────────────────
    DiscoveryMix:
      type: object
      required: [id, label, flavor, track_count, generated_at]
      properties:
        id:
          type: string
          format: uuid
        label:
          type: string
          example: MIX 1
        # [FIX-12] Removed unused taste_profile value
        flavor:
          type: string
          enum: [listening_history]
          example: listening_history
        genre_name:
          type: string
          nullable: true
        cover_image:
          type: string
          format: uri
          nullable: true
        track_count:
          type: integer
        generated_at:
          type: string
          format: date-time
        preview_track:
          allOf:
            - $ref: '#/components/schemas/DiscoveryTrack'
          nullable: true
          description: |
            First track of this mix for instant playback from Home screen.
            null if mix has no tracks.

    DiscoveryStation:
      type: object
      required: [id, artist_id, artist_name, images, preview_track, track_count, is_saved]
      example:
        id: d3d8c9a0-8c6f-4a98-a5a4-b5c2d70bc1f1
        artist_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        artist_name: DJ Karim
        images:
          left: https://cdn.rythmify.com/covers/track1.jpg
          center: null
          right: https://cdn.rythmify.com/covers/track2.jpg
        preview_track:
          id: e5f6a7b8-c9d0-1234-efab-567890abcdef
          title: Midnight Run
          cover_image: https://cdn.rythmify.com/covers/track1.jpg
          duration: 213
          genre_name: Electronic
          play_count: 18
          like_count: 8
          repost_count: 3
          user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          artist_name: DJ Karim
          stream_url: https://cdn.rythmify.com/tracks/e5f6a7b8/stream.mp3
          created_at: '2026-03-01T10:00:00Z'
        track_count: 4
      properties:
        id:
          type: string
          format: uuid
        artist_id:
          type: string
          format: uuid
        artist_name:
          type: string
        images:
          type: object
          required: [left, center, right]
          properties:
            left:
              type: string
              format: uri
              nullable: true
            center:
              type: string
              format: uri
              nullable: true
            right:
              type: string
              format: uri
              nullable: true
        preview_track:
          $ref: '#/components/schemas/DiscoveryTrack'
        track_count:
          type: integer
        is_saved:
          type: boolean
          description: Whether the authenticated viewer has saved this station.
          example: false

    DiscoveryAlbum:
      type: object
      required: [id, name, owner_id, owner_name, track_count, like_count, is_liked_by_me]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        cover_image:
          type: string
          format: uri
          nullable: true
        owner_id:
          type: string
          format: uuid
        owner_name:
          type: string
        track_count:
          type: integer
        like_count:
          type: integer
        created_at:
          type: string
          format: date-time
        preview_track:
          allOf:
            - $ref: '#/components/schemas/DiscoveryTrack'
          nullable: true
          description: |
            First track in album order (position ASC NULLS LAST, then created_at ASC).
            null if album has no tracks.
        is_liked_by_me:
          type: boolean
          description: Whether the authenticated viewer has liked this album.
          example: false

    CuratedMixSummary:
      type: object
      required: [id, label, description, track_count, refreshes_at, preview_track, is_liked_by_me]
      properties:
        id:
          type: string
          format: uuid
        label:
          type: string
          example: Daily Drops
        description:
          type: string
        track_count:
          type: integer
        refreshes_at:
          type: string
          format: date-time
        cover_url:
          type: string
          format: uri
          nullable: true
        preview_track:
          $ref: '#/components/schemas/DiscoveryTrack'
        is_liked_by_me:
          type: boolean
          description: Whether the authenticated viewer has saved this generated mix.
          example: false

    SavedStation:
      type: object
      required: [id, artist_id, artist_name, track_count, follower_count, saved_at, type]
      properties:
        id:
          type: string
          format: uuid
        artist_id:
          type: string
          format: uuid
        artist_name:
          type: string
        profile_picture:
          type: string
          format: uri
          nullable: true
        track_count:
          type: integer
        follower_count:
          type: integer
        saved_at:
          type: string
          format: date-time
        type:
          type: string
          enum: [artist_station]

    SavedStationsResponse:
      type: object
      required: [data, meta, message]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SavedStation'
        meta:
          $ref: '#/components/schemas/ListMeta'
        message:
          type: string
          example: Saved stations fetched successfully.

    TrackRadioLikeData:
      type: object
      required: [playlist_id, seed_track_id, title]
      properties:
        playlist_id:
          type: string
          format: uuid
        seed_track_id:
          type: string
          format: uuid
        title:
          type: string
        description:
          type: string
        cover_image:
          type: string
          format: uri
          nullable: true

    TrackRadioLikeResponse:
      type: object
      required: [data, message]
      properties:
        data:
          $ref: '#/components/schemas/TrackRadioLikeData'
        message:
          type: string
          example: Track radio saved to library.

    MixLikeData:
      type: object
      required: [like_id, user_id, playlist_id, mix_id, created_at]
      properties:
        like_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        playlist_id:
          type: string
          format: uuid
        mix_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time

    MixLikeResponse:
      type: object
      required: [data, message]
      properties:
        data:
          $ref: '#/components/schemas/MixLikeData'
        message:
          type: string
          example: Mix liked successfully.

    UnlikeResponse:
      type: object
      required: [data, message]
      properties:
        data:
          type: object
          required: [unliked]
          properties:
            unliked:
              type: boolean
            playlist_id:
              type: string
              format: uuid
              nullable: true
        message:
          type: string

    TrackRadioTracksData:
      type: object
      required: [playlist_id, title, seed_track_id, reference_track, tracks, meta]
      properties:
        playlist_id:
          type: string
          format: uuid
        title:
          type: string
        description:
          type: string
          nullable: true
        cover_image:
          type: string
          format: uri
          nullable: true
        seed_track_id:
          type: string
          format: uuid
        reference_track:
          $ref: '#/components/schemas/DiscoveryTrack'
        tracks:
          type: array
          items:
            $ref: '#/components/schemas/DiscoveryTrack'
        meta:
          $ref: '#/components/schemas/ListMeta'

    TrackRadioTracksResponse:
      type: object
      required: [data, message]
      properties:
        data:
          $ref: '#/components/schemas/TrackRadioTracksData'
        message:
          type: string
          example: Track radio tracks fetched successfully.

    EmergingArtist:
      type: object
      required: [id, display_name, play_velocity]
      properties:
        id:
          type: string
          format: uuid
        display_name:
          type: string
        profile_picture:
          type: string
          format: uri
          nullable: true
        top_genre:
          type: string
          nullable: true
        play_velocity:
          type: integer
        track_count:
          type: integer

    # [FIX-15] Added is_following to SuggestedUser
    SuggestedUser:
      type: object
      required: [id, display_name, is_verified, follower_count, suggestion_source, is_following]
      properties:
        id:
          type: string
          format: uuid
        display_name:
          type: string
        username:
          type: string
          nullable: true
        profile_picture:
          type: string
          format: uri
          nullable: true
        is_verified:
          type: boolean
        follower_count:
          type: integer
        mutual_count:
          type: integer
          nullable: true
          description: Number of mutual follows. Present only when suggestion_source = "mutual".
        suggestion_source:
          type: string
          enum: [mutual, popular]
        # [FIX-15]
        is_following:
          type: boolean
          description: |
            Whether the authenticated user already follows this person.
            Always false for suggestions by definition, but included for
            consistency when this schema is reused in other contexts.
          example: false

    # [FIX-15] Added is_following to SuggestedArtist
    SuggestedArtist:
      type: object
      required: [id, display_name, is_verified, follower_count, is_following]
      properties:
        id:
          type: string
          format: uuid
        display_name:
          type: string
        username:
          type: string
          nullable: true
        profile_picture:
          type: string
          format: uri
          nullable: true
        is_verified:
          type: boolean
        follower_count:
          type: integer
        top_genre:
          type: string
          nullable: true
        # [FIX-15]
        is_following:
          type: boolean
          description: Whether the authenticated user already follows this artist.
          example: false

    GenreDetail:
      type: object
      required: [id, name, track_count, artist_count, playlist_count, album_count]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        cover_image:
          type: string
          format: uri
          nullable: true
        track_count:
          type: integer
        artist_count:
          type: integer
        playlist_count:
          type: integer
        album_count:
          type: integer

    GenreArtist:
      type: object
      required: [id, display_name, is_verified, follower_count, track_count_in_genre]
      properties:
        id:
          type: string
          format: uuid
        display_name:
          type: string
        username:
          type: string
          nullable: true
        profile_picture:
          type: string
          format: uri
          nullable: true
        is_verified:
          type: boolean
        follower_count:
          type: integer
        track_count_in_genre:
          type: integer

    GenrePlaylist:
      type: object
      required: [id, name, owner_id, owner_name, track_count, like_count, source]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        cover_image:
          type: string
          format: uri
          nullable: true
        owner_id:
          type: string
          format: uuid
        owner_name:
          type: string
        track_count:
          type: integer
        like_count:
          type: integer
        source:
          type: string
          enum: [tagged, inferred]
        created_at:
          type: string
          format: date-time

    GenreAlbum:
      type: object
      required: [id, name, owner_id, owner_name, track_count, like_count]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        cover_image:
          type: string
          format: uri
          nullable: true
        owner_id:
          type: string
          format: uuid
        owner_name:
          type: string
        track_count:
          type: integer
        like_count:
          type: integer
        release_date:
          type: string
          format: date
          nullable: true

    # [FIX-5] made_for_you is nullable for unauthenticated users
    # [FIX-9] genre_id is required (not nullable) in trending_by_genre
    HomeResponse:
      type: object
      required: [data, message]
      properties:
        data:
          type: object
          required:
            - hot_for_you
            - trending_by_genre
            - artists_to_watch
            - discover_with_stations
          properties:
            curated:
              nullable: true
              description: |
                Guest-only curated discovery section.
                Contains preview-only mix cards generated from multi-genre combinations.
                Not returned for authenticated users.
              allOf:
                - $ref: '#/components/schemas/CuratedHomeSection'
            hot_for_you:
              type: object
              required: [track, valid_until]
              properties:
                track:
                  $ref: '#/components/schemas/DiscoveryTrack'
                reason:
                  type: string
                  nullable: true
                  description: |
                    "Trending in {genre_name}" — unplayed track in user's top genre.
                    "global trending" — authenticated, no genre match.
                    null — unauthenticated user.
                valid_until:
                  type: string
                  format: date-time
            trending_by_genre:
              type: object
              required: [genres, initial_tab]
              properties:
                genres:
                  type: array
                  items:
                    type: object
                    required: [genre_id, genre_name, preview_track, is_liked]
                    properties:
                      genre_id:
                        type: string
                        format: uuid
                      genre_name:
                        type: string
                      preview_track:
                        $ref: '#/components/schemas/DiscoveryTrack'
                      is_liked:
                        type: boolean
                        description: Whether the authenticated viewer has saved this genre feed.
                        example: false
                initial_tab:
                  type: object
                  required: [genre_id, genre_name, tracks]
                  properties:
                    genre_id:
                      type: string
                      format: uuid
                    genre_name:
                      type: string
                    tracks:
                      type: array
                      items:
                        $ref: '#/components/schemas/DiscoveryTrack'
            more_of_what_you_like:
              nullable: true
              description: |
                null for unauthenticated users.
                Present only for authenticated users.
              allOf:
                - type: object
                  required: [tracks, source]
                  properties:
                    tracks:
                      type: array
                      items:
                        $ref: '#/components/schemas/DiscoveryTrack'
                    source:
                      type: string
                      enum: [personalized, trending_fallback]
            albums_for_you:
              nullable: true
              description: |
                null for unauthenticated users.
                Present only for authenticated users.
              allOf:
                - type: array
                  items:
                    $ref: '#/components/schemas/DiscoveryAlbum'
            mixed_for_you:
              nullable: true
              description: |
                null for unauthenticated users.
                Present only for authenticated users.
              allOf:
                - type: array
                  maxItems: 6
                  items:
                    $ref: '#/components/schemas/HomeMixPreview'
            # [FIX-5] made_for_you is nullable — null for unauthenticated users
            made_for_you:
              nullable: true
              description: |
                null for unauthenticated users (requires auth to generate).
                When null, the FE should hide the Made For You section.
                When source = "trending_fallback", display generic labels.
              allOf:
                - type: object
                  required: [daily_mix, weekly_mix]
                  properties:
                    daily_mix:
                      $ref: '#/components/schemas/CuratedMixSummary'
                    weekly_mix:
                      $ref: '#/components/schemas/CuratedMixSummary'
            artists_to_watch:
              type: array
              maxItems: 10
              items:
                $ref: '#/components/schemas/EmergingArtist'
            discover_with_stations:
              type: array
              maxItems: 10
              example:
                - id: d3d8c9a0-8c6f-4a98-a5a4-b5c2d70bc1f1
                  artist_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  artist_name: DJ Karim
                  images:
                    left: https://cdn.rythmify.com/covers/track1.jpg
                    center: https://cdn.rythmify.com/covers/artist.jpg
                    right: https://cdn.rythmify.com/covers/track2.jpg
                  preview_track:
                    id: e5f6a7b8-c9d0-1234-efab-567890abcdef
                    title: Midnight Run
                    cover_image: https://cdn.rythmify.com/covers/track1.jpg
                    duration: 213
                    genre_name: Electronic
                    play_count: 18
                    like_count: 8
                    repost_count: 3
                    user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    artist_name: DJ Karim
                    stream_url: https://cdn.rythmify.com/tracks/e5f6a7b8/stream.mp3
                    created_at: '2026-03-01T10:00:00Z'
                  track_count: 4
              items:
                $ref: '#/components/schemas/DiscoveryStation'
        message:
          type: string
          example: Home page data fetched successfully.

    TrendingByGenreTabResponse:
      type: object
      required: [data, message]
      properties:
        data:
          type: object
          required: [genre_id, genre_name, tracks, pagination, is_liked]
          properties:
            genre_id:
              type: string
              format: uuid
            genre_name:
              type: string
            tracks:
              type: array
              items:
                $ref: '#/components/schemas/DiscoveryTrack'
            pagination:
              $ref: '#/components/schemas/ListMeta'
            is_liked:
              type: boolean
              description: Whether the authenticated viewer has saved this genre feed.
              example: false
        message:
          type: string

    HotForYouResponse:
      type: object
      required: [data, message]
      properties:
        data:
          type: object
          required: [track, valid_until]
          properties:
            track:
              $ref: '#/components/schemas/DiscoveryTrack'
            reason:
              type: string
              nullable: true
            valid_until:
              type: string
              format: date-time
        message:
          type: string

    MoreOfWhatYouLikeResponse:
      type: object
      required: [data, source, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DiscoveryTrack'
        source:
          type: string
          enum: [personalized, trending_fallback]
        pagination:
          $ref: '#/components/schemas/ListMeta'

    MixDetails:
      type: object
      required: [mix_id, title, tracks]
      properties:
        mix_id:
          type: string
          example: mix_genre_123e4567-e89b-12d3-a456-426614174000
        title:
          type: string
          example: Electronic Mix
        cover_url:
          type: string
          format: uri
          nullable: true
          example: https://cdn.rythmify.com/covers/track1.jpg
        tracks:
          type: array
          items:
            $ref: '#/components/schemas/DiscoveryTrack'

    MixDetailsResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/MixDetails'

    HomeMixPreview:
      type: object
      required: [mix_id, title, preview_track, is_liked_by_me]
      properties:
        mix_id:
          type: string
          example: mix_genre_123e4567-e89b-12d3-a456-426614174000
        title:
          type: string
          example: Electronic Mix
        cover_url:
          type: string
          format: uri
          nullable: true
          example: https://cdn.rythmify.com/covers/track1.jpg
        preview_track:
          $ref: '#/components/schemas/DiscoveryTrack'
        is_liked_by_me:
          type: boolean
          description: Whether the authenticated viewer has saved this mix.
          example: false

    CuratedHomeSection:
      type: object
      required: [mixes]
      properties:
        mixes:
          type: array
          description: |
            Preview-only curated discovery mixes.
            Generated dynamically from top-performing genres with controlled randomness.
          items:
            $ref: '#/components/schemas/CuratedHomeMixPreview'

    CuratedHomeMixPreview:
      type: object
      required: [mix_id, title, preview_track]
      properties:
        mix_id:
          type: string
          description: |
            Deterministic identifier based on the genre combination.
            Format: mix_custom_<genreId1>_<genreId2>.
            Used for frontend discovery cards only.
          example: mix_custom_123e4567-e89b-12d3-a456-426614174000_223e4567-e89b-12d3-a456-426614174111
        title:
          type: string
          description: Generated title (editorial or genre-based label).
          example: Night Drive
        cover_url:
          type: string
          format: uri
          nullable: true
          description: Cover image derived from the top selected track in this mix preview.
          example: https://cdn.rythmify.com/covers/track1.jpg
        preview_track:
          description: Representative track for quick preview in discovery UI.
          $ref: '#/components/schemas/DiscoveryTrack'

    StationListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          example:
            - id: d3d8c9a0-8c6f-4a98-a5a4-b5c2d70bc1f1
              artist_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              artist_name: DJ Karim
              images:
                left: https://cdn.rythmify.com/covers/track1.jpg
                center: null
                right: https://cdn.rythmify.com/covers/track2.jpg
              preview_track:
                id: e5f6a7b8-c9d0-1234-efab-567890abcdef
                title: Midnight Run
                cover_image: https://cdn.rythmify.com/covers/track1.jpg
                duration: 213
                genre_name: Electronic
                play_count: 18
                like_count: 8
                repost_count: 3
                user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                artist_name: DJ Karim
                stream_url: https://cdn.rythmify.com/tracks/e5f6a7b8/stream.mp3
                created_at: '2026-03-01T10:00:00Z'
              track_count: 4
          items:
            $ref: '#/components/schemas/DiscoveryStation'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    StationTracksResponse:
      type: object
      required: [data, station, pagination]
      properties:
        station:
          $ref: '#/components/schemas/DiscoveryStation'
        data:
          type: array
          items:
            $ref: '#/components/schemas/DiscoveryTrack'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    AlbumsForYouResponse:
      type: object
      required: [data, source, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DiscoveryAlbum'
        source:
          type: string
          enum: [followed_artists, global_fallback]
        pagination:
          $ref: '#/components/schemas/ListMeta'

    ArtistsToWatchResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/EmergingArtist'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    SuggestedUsersResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SuggestedUser'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    SuggestedArtistsResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SuggestedArtist'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    RelatedTracksResponse:
      type: object
      required: [data, message]
      properties:
        data:
          type: object
          required: [reference_track, tracks, meta]
          properties:
            reference_track:
              $ref: '#/components/schemas/DiscoveryTrack'
            tracks:
              type: array
              items:
                $ref: '#/components/schemas/DiscoveryTrack'
            meta:
              $ref: '#/components/schemas/ListMeta'
        message:
          type: string
          example: Related tracks fetched successfully.

    IntroducingSection:
      type: object
      nullable: true
      description: Featured playlist for the genre with preview tracks.
      properties:
        playlist:
          $ref: '#/components/schemas/Playlist'
        tracks_preview:
          type: array
          maxItems: 3
          items:
            $ref: '#/components/schemas/DiscoveryTrack'

    GenrePageResponse:
      type: object
      required: [data, message]
      properties:
        data:
          type: object
          required: [genre, playlists, albums, artists, tracks]
          properties:
            genre:
              $ref: '#/components/schemas/GenreDetail'
            introducing:
              $ref: '#/components/schemas/IntroducingSection'
            playlists:
              type: array
              items:
                $ref: '#/components/schemas/GenrePlaylist'
            albums:
              type: array
              items:
                $ref: '#/components/schemas/GenreAlbum'
            artists:
              type: array
              items:
                $ref: '#/components/schemas/GenreArtist'
            tracks:
              type: array
              items:
                $ref: '#/components/schemas/DiscoveryTrack'
        message:
          type: string

    GenreTracksResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DiscoveryTrack'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    GenreAlbumsResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/GenreAlbum'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    GenrePlaylistsResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/GenrePlaylist'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    GenreArtistsResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/GenreArtist'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    # ── Messaging schemas ─────────────────────────────────────
    Conversation:
      type: object
      properties:
        id:
          type: string
          format: uuid
        participant:
          $ref: '#/components/schemas/PublicUser'
        last_message:
          $ref: '#/components/schemas/Message'
        unread_count:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    Message:
      type: object
      properties:
        id:
          type: string
          format: uuid
        conversation_id:
          type: string
          format: uuid
        sender_id:
          type: string
          format: uuid
        body:
          type: string
          nullable: true
        embed_type:
          type: string
          enum: [track, playlist]
          nullable: true
        embed_id:
          type: string
          format: uuid
          nullable: true
        is_read:
          type: boolean
          default: false
        created_at:
          type: string
          format: date-time

    SendMessageRequest:
      type: object
      properties:
        body:
          type: string
          nullable: true
          maxLength: 2000
        resource:
          type: object
          nullable: true
          required: [type, id]
          properties:
            type:
              type: string
              enum: [track, playlist]
            id:
              type: string
              format: uuid

    StartConversationRequest:
      type: object
      required: [recipient_id]
      properties:
        recipient_id:
          type: string
          format: uuid
        body:
          type: string
          nullable: true
          maxLength: 2000
        resource:
          type: object
          nullable: true
          required: [type, id]
          properties:
            type:
              type: string
              enum: [track, playlist]
            id:
              type: string
              format: uuid

    EnsureConversationRequest:
      type: object
      required: [recipient_id]
      properties:
        recipient_id:
          type: string
          format: uuid

    ConversationListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Conversation'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    ConversationDetailResponse:
      type: object
      required: [data, pagination, conversation]
      properties:
        conversation:
          $ref: '#/components/schemas/Conversation'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Message'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    ConversationCreatedResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            conversation:
              $ref: '#/components/schemas/Conversation'
            message:
              $ref: '#/components/schemas/Message'

    MessageCreatedResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Message'

    EnsureConversationResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            conversation:
              $ref: '#/components/schemas/Conversation'

    UnreadCountResponse:
      type: object
      properties:
        data:
          type: object
          required: [unread_count]
          properties:
            unread_count:
              type: integer
              example: 5

    MarkMessageReadRequest:
      type: object
      required: [is_read]
      properties:
        is_read:
          type: boolean

    MarkMessageReadResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            message_id:
              type: string
              format: uuid
            is_read:
              type: boolean
            conversation_unread_count:
              type: integer

    # ── Notification schemas ──────────────────────────────────
    NotificationActor:
      type: object
      properties:
        id:
          type: string
          format: uuid
        username:
          type: string
          nullable: true
        display_name:
          type: string
          nullable: true
        avatar:
          type: string
          format: uri
          nullable: true

    NotificationResourceDetails:
      type: object
      description: Conditional resource details depending on notification reference type.
      nullable: true
      properties:
        title:
          type: string
        content:
          type: string

    Notification:
      type: object
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum: [follow, like, repost, comment, new_post_by_followed]
        actor:
          $ref: '#/components/schemas/NotificationActor'
        resource_type:
          type: string
          enum: [track, playlist, comment]
          nullable: true
        resource_id:
          type: string
          format: uuid
          nullable: true
        resource_details:
          $ref: '#/components/schemas/NotificationResourceDetails'
        is_read:
          type: boolean
          default: false
        created_at:
          type: string
          format: date-time

    NotificationListResponse:
      type: object
      required: [data, message]
      properties:
        data:
          type: object
          required: [items, unread_count, pagination]
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/Notification'
            unread_count:
              type: integer
              minimum: 0
            pagination:
              type: object
              required: [page, per_page, total_items, total_pages, has_next, has_prev]
              properties:
                page:
                  type: integer
                  minimum: 1
                per_page:
                  type: integer
                  minimum: 1
                total_items:
                  type: integer
                  minimum: 0
                total_pages:
                  type: integer
                  minimum: 0
                has_next:
                  type: boolean
                has_prev:
                  type: boolean
        message:
          type: string

    RegisterPushTokenRequest:
      type: object
      required: [token, platform]
      properties:
        token:
          type: string
        platform:
          type: string
          enum: [android, ios]

    UnregisterPushTokenRequest:
      type: object
      required: [token]
      properties:
        token:
          type: string

    NotificationPreferences:
      type: object
      properties:
        new_follower_push: { type: boolean, default: true }
        new_follower_email: { type: boolean, default: false }
        repost_of_your_post_push: { type: boolean, default: true }
        repost_of_your_post_email: { type: boolean, default: false }
        new_post_by_followed_push: { type: boolean, default: false }
        new_post_by_followed_email: { type: boolean, default: false }
        likes_and_plays_push: { type: boolean, default: false }
        likes_and_plays_email: { type: boolean, default: false }
        comment_on_post_push: { type: boolean, default: true }
        comment_on_post_email: { type: boolean, default: false }
        recommended_content_push: { type: boolean, default: false }
        recommended_content_email: { type: boolean, default: false }
        new_message_push: { type: boolean, default: true }
        new_message_email:
          type: boolean
          default: false
          description: Send an email when a new direct message is received.
        messages_from:
          type: string
          enum: [everyone, followers_only, nobody]
          default: everyone
        feature_updates_push: { type: boolean, default: true }
        feature_updates_email: { type: boolean, default: true }
        surveys_and_feedback_push: { type: boolean, default: false }
        surveys_and_feedback_email: { type: boolean, default: false }
        promotional_content_push: { type: boolean, default: false }
        promotional_content_email: { type: boolean, default: false }
        newsletter_email: { type: boolean, default: false }

    UpdateNotificationPreferencesRequest:
      type: object
      description: All fields optional. Only provided fields are updated.
      properties:
        new_follower_push: { type: boolean }
        new_follower_email: { type: boolean }
        repost_of_your_post_push: { type: boolean }
        repost_of_your_post_email: { type: boolean }
        new_post_by_followed_push: { type: boolean }
        new_post_by_followed_email: { type: boolean }
        likes_and_plays_push: { type: boolean }
        likes_and_plays_email: { type: boolean }
        comment_on_post_push: { type: boolean }
        comment_on_post_email: { type: boolean }
        recommended_content_push: { type: boolean }
        recommended_content_email: { type: boolean }
        new_message_push: { type: boolean }
        new_message_email:
          type: boolean
          description: Toggle email delivery for new direct messages.
        messages_from:
          type: string
          enum: [everyone, followers_only, nobody]
        feature_updates_push: { type: boolean }
        feature_updates_email: { type: boolean }
        surveys_and_feedback_push: { type: boolean }
        surveys_and_feedback_email: { type: boolean }
        promotional_content_push: { type: boolean }
        promotional_content_email: { type: boolean }
        newsletter_email: { type: boolean }
      additionalProperties: false

    NotificationPreferencesResponse:
      type: object
      required: [data, message]
      properties:
        data:
          $ref: '#/components/schemas/NotificationPreferences'
        message:
          type: string

    # ── Moderation schemas ────────────────────────────────────
    ReportRequest:
      type: object
      required: [resource_type, resource_id, reason]
      properties:
        resource_type:
          type: string
          enum: [track, user]
        resource_id:
          type: string
          format: uuid
        reason:
          type: string
          enum: [copyright, inappropriate, spam, impersonation]
          description: |
            copyright and inappropriate are valid for tracks.
            inappropriate, spam, and impersonation are valid for users.
            copyright is NOT valid for users.
        description:
          type: string
          maxLength: 1000

    Report:
      type: object
      required: [id, resource_type, resource_id, reason, status, created_at]
      properties:
        id:
          type: string
          format: uuid
        resource_type:
          type: string
          enum: [track, user]
        resource_id:
          type: string
          format: uuid
        reason:
          type: string
          enum: [copyright, inappropriate, spam, impersonation]
        status:
          type: string
          enum: [pending, resolved, dismissed]
        created_at:
          type: string
          format: date-time

    ReportDetailed:
      allOf:
        - $ref: '#/components/schemas/Report'
        - type: object
          properties:
            description:
              type: string
            resource:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                title:
                  type: string
                  nullable: true
                display_name:
                  type: string
                  nullable: true
            reported_by:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                display_name:
                  type: string

    AnalyticsSummary:
      type: object
      properties:
        period:
          type: string
        active_users:
          type: integer
        new_registrations:
          type: integer
        total_tracks:
          type: integer
        total_plays:
          type: integer
        play_through_rate:
          type: number
          format: float
        storage_used_gb:
          type: number
          format: float
        storage_limit_gb:
          type: number
          format: float
        pending_reports:
          type: integer
        suspended_accounts:
          type: integer

    ReportAppeal:
      type: object
      required: [id, report_id, status, created_at]
      properties:
        id:
          type: string
          format: uuid
        report_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        appeal_reason:
          type: string
        status:
          type: string
          enum: [pending, upheld, overturned]
        admin_notes:
          type: string
          nullable: true
        decision_made_by:
          type: string
          format: uuid
          nullable: true
        decided_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        original_report:
          type: object
          properties:
            id:
              type: string
              format: uuid
            reason:
              type: string
            resource_type:
              type: string

    # ── Subscription schemas ──────────────────────────────────
    SubscriptionPlanName:
      type: string
      enum: [free, premium]

    SubscriptionPlan:
      type: object
      required:
        - subscription_plan_id
        - name
        - display_name
        - price
        - duration_days
        - duration_minutes
        - track_limit
        - playlist_limit
      properties:
        subscription_plan_id:
          type: integer
        name:
          $ref: '#/components/schemas/SubscriptionPlanName'
        display_name:
          type: string
          enum: [Free, Go+, Artist Pro]
          description: User-facing plan name derived from the real plan and user role.
        price:
          type: string
          example: '4.99'
        duration_days:
          type: integer
          nullable: true
          description: Duration in days. Nullable; demo premium currently uses minutes instead.
        duration_minutes:
          type: integer
          nullable: true
          description: Duration in minutes. Demo premium uses 5 minutes; free has null.
        track_limit:
          type: integer
          nullable: true
          description: Null means unlimited.
        playlist_limit:
          type: integer
          nullable: true
          description: Null means unlimited.

    SubscriptionPlanListResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [items]
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/SubscriptionPlan'
        message:
          type: string

    UserSubscriptionStatus:
      type: string
      enum: [pending, active, canceled, expired]

    SubscriptionUsage:
      type: object
      required:
        [
          tracks_uploaded,
          track_limit,
          playlists_created,
          playlist_limit,
          can_upload_track,
          can_create_playlist,
          offline_listening_enabled,
        ]
      properties:
        tracks_uploaded:
          type: integer
          minimum: 0
        track_limit:
          type: integer
          nullable: true
          description: Null means unlimited.
        playlists_created:
          type: integer
          minimum: 0
        playlist_limit:
          type: integer
          nullable: true
          description: Null means unlimited.
        can_upload_track:
          type: boolean
        can_create_playlist:
          type: boolean
        offline_listening_enabled:
          type: boolean

    MySubscription:
      type: object
      description: Effective current subscription view for the authenticated user. Users without active premium access receive the free plan with null subscription dates and null `user_subscription_id`.
      required: [user_subscription_id, status, auto_renew, start_date, end_date, plan, usage]
      properties:
        user_subscription_id:
          type: integer
          nullable: true
          description: Null only for the default effective free plan.
        status:
          $ref: '#/components/schemas/UserSubscriptionStatus'
        auto_renew:
          type: boolean
        start_date:
          type: string
          format: date-time
          nullable: true
        end_date:
          type: string
          format: date-time
          nullable: true
        plan:
          $ref: '#/components/schemas/SubscriptionPlan'
        usage:
          $ref: '#/components/schemas/SubscriptionUsage'

    MySubscriptionResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/MySubscription'
        message:
          type: string

    SubscriptionCheckoutRequest:
      type: object
      required: [subscription_plan_id]
      properties:
        subscription_plan_id:
          type: integer
      additionalProperties: false

    PaymentMethod:
      type: string
      enum: [mock]

    SubscriptionCheckoutStatus:
      type: string
      enum: [pending, paid, failed]

    SubscriptionCheckoutResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required:
            [
              transaction_id,
              user_subscription_id,
              checkout_status,
              payment_method,
              payment_url,
              plan,
            ]
          properties:
            transaction_id:
              type: integer
            user_subscription_id:
              type: integer
            checkout_status:
              $ref: '#/components/schemas/SubscriptionCheckoutStatus'
            payment_method:
              $ref: '#/components/schemas/PaymentMethod'
            payment_url:
              type: string
              format: uri
            plan:
              $ref: '#/components/schemas/SubscriptionPlan'
        message:
          type: string

    CancelSubscriptionResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [user_subscription_id, status, auto_renew, end_date]
          properties:
            user_subscription_id:
              type: integer
            status:
              $ref: '#/components/schemas/UserSubscriptionStatus'
            auto_renew:
              type: boolean
            end_date:
              type: string
              format: date-time
              nullable: true
        message:
          type: string

    PaymentStatus:
      type: string
      enum: [pending, paid, failed]

    SubscriptionTransaction:
      type: object
      required:
        [
          transaction_id,
          user_subscription_id,
          amount,
          payment_method,
          payment_status,
          paid_at,
          created_at,
        ]
      properties:
        transaction_id:
          type: integer
        user_subscription_id:
          type: integer
        amount:
          type: string
        payment_method:
          $ref: '#/components/schemas/PaymentMethod'
        payment_status:
          $ref: '#/components/schemas/PaymentStatus'
        paid_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time

    SubscriptionTransactionListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionTransaction'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    MockConfirmSubscriptionResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [transaction_id, payment_status, paid_at, subscription]
          properties:
            transaction_id:
              type: integer
            payment_status:
              $ref: '#/components/schemas/PaymentStatus'
            paid_at:
              type: string
              format: date-time
            subscription:
              type: object
              required: [user_subscription_id, status, auto_renew, start_date, end_date, plan]
              properties:
                user_subscription_id:
                  type: integer
                status:
                  $ref: '#/components/schemas/UserSubscriptionStatus'
                auto_renew:
                  type: boolean
                start_date:
                  type: string
                  format: date-time
                end_date:
                  type: string
                  format: date-time
                  nullable: true
                plan:
                  $ref: '#/components/schemas/SubscriptionPlan'
        message:
          type: string

    # ── Social graph schemas ──────────────────────────────────
    ListMeta2:
      $ref: '#/components/schemas/ListMeta'

    UserListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/UserSummary'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    FollowResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            follower_id:
              type: string
              format: uuid
            followed_id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
        message:
          type: string

    FollowStatus:
      type: object
      properties:
        is_following:
          type: boolean
        is_followed_by:
          type: boolean
        is_blocking:
          type: boolean
        is_blocked_by:
          type: boolean

    BlockResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            blocker_id:
              type: string
              format: uuid
            blocked_id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
        message:
          type: string

    FollowRequestResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            request_id:
              type: string
              format: uuid
            follower_id:
              type: string
              format: uuid
            following_id:
              type: string
              format: uuid
            status:
              type: string
              enum: [pending, accepted, rejected]
            accepted_at:
              type: string
              format: date-time
        message:
          type: string

    # ── Engagement schemas ────────────────────────────────────
    LikeResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            like_id:
              type: string
              format: uuid
            user_id:
              type: string
              format: uuid
            track_id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
        message:
          type: string

    CommentLikeResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            user_id:
              type: string
              format: uuid
            comment_id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
        message:
          type: string

    RepostResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            repost_id:
              type: string
              format: uuid
            user_id:
              type: string
              format: uuid
            track_id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
        message:
          type: string

    PlaylistLikeResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            like_id:
              type: string
              format: uuid
            user_id:
              type: string
              format: uuid
            playlist_id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
        message:
          type: string

    PlaylistRepostResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            repost_id:
              type: string
              format: uuid
            user_id:
              type: string
              format: uuid
            playlist_id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
        message:
          type: string

    AlbumLikeResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            like_id:
              type: string
              format: uuid
            user_id:
              type: string
              format: uuid
            album_id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
        message:
          type: string

    AlbumRepostResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            repost_id:
              type: string
              format: uuid
            user_id:
              type: string
              format: uuid
            album_id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
        message:
          type: string

    Comment:
      type: object
      description: |
        A timestamped comment on a track. Supports nested replies.

        Performance notes:
        - `reply_count` must be denormalized (stored column, not COUNT subquery) to avoid O(n) lookups during pagination.
          Backend: Add column `reply_count INTEGER DEFAULT 0`, increment on POST reply, decrement on DELETE reply.
          Protected against race conditions: uses pg_advisory_xact_lock() for concurrent inserts.

        - `updated_at` column tracks edit timestamps. Must be updated on every PATCH operation.

        - Sorting is always DETERMINISTIC via tie-breaking:
          ORDER BY [primary_sort_column], created_at ASC, id ASC
          This ensures identical results across queries (no comment jumping during pagination).

        - Database index REQUIRED for waveform queries: CREATE INDEX ON "comments" ("track_id", "track_timestamp", "created_at", "id")
          This covers: timestamp filtering, full sorting, zero in-memory sort operations.
      properties:
        comment_id:
          type: string
          format: uuid
        track_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        parent_comment_id:
          type: string
          format: uuid
          nullable: true
        content:
          type: string
          minLength: 1
          maxLength: 500
        track_timestamp:
          type: integer
          minimum: 0
          description: Position in the track (in seconds) where this comment was posted.
        like_count:
          type: integer
        reply_count:
          type: integer
          description: Total nested replies (must be denormalized, not computed at query time).
        is_liked_by_me:
          type: boolean
        is_user_blocked:
          type: boolean
        author:
          $ref: '#/components/schemas/UserSummary'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          nullable: true
          description: Set when comment is edited. Null if never edited.

    CommentListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Comment'
        pagination:
          $ref: '#/components/schemas/ListMeta'

    CommentSingleResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/Comment'

    CommentCreatedResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/Comment'
        message:
          type: string

    CreateCommentRequest:
      type: object
      required: [content, track_timestamp]
      properties:
        content:
          type: string
          minLength: 1
          maxLength: 500
        track_timestamp:
          type: integer
          minimum: 0

    UpdateCommentRequest:
      type: object
      required: [content]
      properties:
        content:
          type: string
          minLength: 1
          maxLength: 500

    CreateReplyRequest:
      type: object
      required: [content]
      properties:
        content:
          type: string
          minLength: 1
          maxLength: 500