openapi: 3.0.0
info:
  title: Api
  version: 0.0.0
servers:
  - url: "http://localhost:8080"
paths:
  /promocodes:
    get:
      tags:
        - PromocodesApiV2
      summary: listPromocodes
      description: GET /api/v2/promocodes\nLists available promocodes for current user.\nReturns active campaigns with promocodes that user can apply.
      operationId: listPromocodes
      responses:
        200:
          description: "Operation completed!"
  /promocodes/<code>/validate:
    get:
      tags:
        - PromocodesApiV2
      summary: validatePromocode
      description: "GET /api/v2/promocodes/{code}/validate\nValidates a promocode without applying it.\nReturns validation result with valid: true/false and message."
      operationId: validatePromocode
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /promocodes/<code>/apply:
    post:
      tags:
        - PromocodesApiV2
      summary: applyPromocode
      description: "POST /api/v2/promocodes/{code}/apply\nApplies promocode for current user."
      operationId: applyPromocode
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /admin/promocodes:
    get:
      tags:
        - PromocodesApiV2
      summary: listPromoCodeCampaigns
      description: GET /api/v2/admin/promocodes\nLists promocode campaigns (admin only).
      operationId: listPromoCodeCampaigns
      responses:
        200:
          description: "Operation completed!"
    post:
      tags:
        - PromocodesApiV2
      summary: upsertPromoCodeCampaign
      description: POST /api/v2/admin/promocodes\nCreates or updates promocode campaign (admin only).
      operationId: upsertPromoCodeCampaign
      responses:
        200:
          description: "Operation completed!"
  /admin/promocodes/<id>:
    get:
      tags:
        - PromocodesApiV2
      summary: getPromoCodeCampaign
      description: "GET /api/v2/admin/promocodes/{id}\nReturns promocode campaign details (admin only)."
      operationId: getPromoCodeCampaign
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
    delete:
      tags:
        - PromocodesApiV2
      summary: deletePromoCodeCampaign
      description: "DELETE /api/v2/admin/promocodes/{id}\nDeletes promocode campaign (admin only)."
      operationId: deletePromoCodeCampaign
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /admin/discounts:
    get:
      tags:
        - DiscountsApiV2
      summary: GET /api/v2/admin/discounts
      operationId: listDiscountCampaigns
      responses:
        200:
          description: "Operation completed!"
    post:
      tags:
        - DiscountsApiV2
      summary: POST /api/v2/admin/discounts
      operationId: addDiscountCampaign
      responses:
        200:
          description: "Operation completed!"
  /admin/discounts/<id>:
    delete:
      tags:
        - DiscountsApiV2
      summary: "DELETE /api/v2/admin/discounts/{id}"
      operationId: deleteDiscountCampaign
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /cards:
    get:
      tags:
        - AdminCardsApiV2
      summary: getAllCards
      operationId: getAllCards
      responses:
        200:
          description: "Operation completed!"
    post:
      tags:
        - AdminCardsApiV2
      summary: createCard
      operationId: createCard
      responses:
        200:
          description: "Operation completed!"
  /cards/<cardId>:
    get:
      tags:
        - AdminCardsApiV2
      summary: getCard
      operationId: getCard
      parameters:
        - name: cardId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
    put:
      tags:
        - AdminCardsApiV2
      summary: updateCard
      operationId: updateCard
      parameters:
        - name: cardId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
    delete:
      tags:
        - AdminCardsApiV2
      summary: deleteCard
      operationId: deleteCard
      parameters:
        - name: cardId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /subscriptions/plans:
    get:
      tags:
        - SubscriptionsApiV2
      summary: getPlans
      description: GET /api/v2/subscriptions/plans\nList available subscription plans\nReturns all available subscription plans. Authentication is optional.
      operationId: getPlans
      responses:
        200:
          description: "Operation completed!"
  /subscriptions/purchase:
    post:
      tags:
        - SubscriptionsApiV2
      summary: purchase
      description: POST /api/v2/subscriptions/purchase\nPurchase a subscription
      operationId: purchase
      responses:
        200:
          description: "Operation completed!"
  /subscriptions/status:
    get:
      tags:
        - SubscriptionsApiV2
      summary: getStatus
      description: GET /api/v2/subscriptions/status\nGet current user subscription status
      operationId: getStatus
      responses:
        200:
          description: "Operation completed!"
  /subscriptions/cancel:
    post:
      tags:
        - SubscriptionsApiV2
      summary: cancel
      description: POST /api/v2/subscriptions/cancel\nCancel user’s subscription
      operationId: cancel
      responses:
        200:
          description: "Operation completed!"
  /users/me:
    get:
      tags:
        - UsersApiV2
      summary: getCurrentUser
      description: GET /api/v2/users/me\nReturns current authenticated user.
      operationId: getCurrentUser
      responses:
        200:
          description: "Operation completed!"
    patch:
      tags:
        - UsersApiV2
      summary: updateCurrentUser
      description: PATCH /api/v2/users/me\nUpdates mutable user fields (currently name and email).
      operationId: updateCurrentUser
      responses:
        200:
          description: "Operation completed!"
  /users/me/settings:
    post:
      tags:
        - UsersApiV2
      summary: updateUserSettings
      description: POST /api/v2/users/me/settings\nUpdates user settings.
      operationId: updateUserSettings
      responses:
        200:
          description: "Operation completed!"
  /users/me/statistics:
    post:
      tags:
        - UsersApiV2
      summary: addUserTestStatistics
      description: POST /api/v2/users/me/statistics\nAdds user test statistics entry.
      operationId: addUserTestStatistics
      responses:
        200:
          description: "Operation completed!"
  /users/me/purchases:
    get:
      tags:
        - UsersApiV2
      summary: getUserPurchases
      description: GET /api/v2/users/me/purchases\nReturns current user's processed purchases.
      operationId: getUserPurchases
      responses:
        200:
          description: "Operation completed!"
  /users/me/statistics/detailed:
    get:
      tags:
        - UsersApiV2
      summary: getDetailedStatistics
      description: "GET /api/v2/users/me/statistics/detailed\nReturns detailed user statistics including streaks, study time, achievements."
      operationId: getDetailedStatistics
      responses:
        200:
          description: "Operation completed!"
  /users/me/statistics/packs:
    get:
      tags:
        - UsersApiV2
      summary: getPacksStatistics
      description: "GET /api/v2/users/me/statistics/packs\nReturns statistics for all user packs or specific pack if packId provided.\nQuery parameters: ?packId=<packId>"
      operationId: getPacksStatistics
      responses:
        200:
          description: "Operation completed!"
  /users/me/statistics/words:
    get:
      tags:
        - UsersApiV2
      summary: getWordsStatistics
      description: "GET /api/v2/users/me/statistics/words\nReturns paginated word statistics with optional filtering.\nQuery parameters:\n- packId: filter by specific pack\n- limit: number of results (default 50, max 100)\n- offset: pagination offset (default 0)\n- sortBy: 'difficulty', 'accuracy', 'recent' (default 'difficulty')\n- needsReview: 'true' to show only words needing review"
      operationId: getWordsStatistics
      responses:
        200:
          description: "Operation completed!"
  /users/me/statistics/timeline:
    get:
      tags:
        - UsersApiV2
      summary: getTimelineStatistics
      description: "GET /api/v2/users/me/statistics/timeline\nReturns timeline statistics for study activity.\nQuery parameters:\n- period: 'day', 'week', 'month', 'year' (default 'month')\n- from: ISO date string for start date\n- to: ISO date string for end date"
      operationId: getTimelineStatistics
      responses:
        200:
          description: "Operation completed!"
  /users/me/sessions:
    post:
      tags:
        - UsersApiV2
      summary: recordStudySession
      description: POST /api/v2/users/me/sessions\nRecords a study session for the user.
      operationId: recordStudySession
      responses:
        200:
          description: "Operation completed!"
  /users/me/achievements:
    get:
      tags:
        - UsersApiV2
      summary: getAchievements
      description: GET /api/v2/users/me/achievements\nReturns user's achievements and progress.
      operationId: getAchievements
      responses:
        200:
          description: "Operation completed!"
  /admin/auth/request-code:
    post:
      tags:
        - AdminAuthApiV2
      summary: requestCode
      description: "POST /api/v2/admin/auth/request-code\nGenerate a web authentication code for admin login\nSimilar to /api/v2/auth/telegram/web-code but for admin panel"
      operationId: requestCode
      responses:
        200:
          description: "Operation completed!"
  /admin/auth/verify-code:
    post:
      tags:
        - AdminAuthApiV2
      summary: verifyCode
      description: "POST /api/v2/admin/auth/verify-code\nVerify authentication code and return JWT token\nCode must be claimed by an admin Telegram user"
      operationId: verifyCode
      responses:
        200:
          description: "Operation completed!"
  /admin/auth/code-status/<code>:
    get:
      tags:
        - AdminAuthApiV2
      summary: getCodeStatus
      description: "GET /api/v2/admin/auth/code-status/<code>\nGet current status for an admin authentication code"
      operationId: getCodeStatus
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /admin/auth/me:
    get:
      tags:
        - AdminAuthApiV2
      summary: getCurrentUser
      description: GET /api/v2/admin/auth/me\nGet current authenticated admin info
      operationId: getCurrentUser
      responses:
        200:
          description: "Operation completed!"
  /auth/oauth/google:
    post:
      tags:
        - AuthApiV2
      summary: authenticateGoogle
      description: POST /api/v2/auth/oauth/google\nAuthenticate with Google ID token
      operationId: authenticateGoogle
      responses:
        200:
          description: "Operation completed!"
  /auth/telegram/generate-code:
    post:
      tags:
        - AuthApiV2
      summary: generateTelegramCode
      description: "POST /api/v2/auth/telegram/generate-code\nGenerate a new Telegram authentication code\nCalled by the Telegram bot when user requests a code\nBody: { telegramUserId: string, telegramUsername?: string, firstName?: string, lastName?: string }"
      operationId: generateTelegramCode
      responses:
        200:
          description: "Operation completed!"
  /auth/telegram/web-code:
    post:
      tags:
        - AuthApiV2
      summary: createWebTelegramCode
      description: "POST /api/v2/auth/telegram/web-code\nGenerates a new Telegram authentication code initiated from the web app"
      operationId: createWebTelegramCode
      responses:
        200:
          description: "Operation completed!"
  /auth/telegram/claim-code:
    post:
      tags:
        - AuthApiV2
      summary: claimTelegramCode
      description: "POST /api/v2/auth/telegram/claim-code\nCalled by Telegram bot when user sends a code generated via the web app\nBody: { code: string, telegramUserId: string, telegramUsername?: string, firstName?: string, lastName?: string }"
      operationId: claimTelegramCode
      responses:
        200:
          description: "Operation completed!"
  /auth/telegram/code-status/<code>:
    get:
      tags:
        - AuthApiV2
      summary: getTelegramCodeStatus
      description: "GET /api/v2/auth/telegram/code-status/<code>\nReturns current status for a Telegram authentication code"
      operationId: getTelegramCodeStatus
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /auth/telegram/web-app:
    post:
      tags:
        - AuthApiV2
      summary: authenticateTelegramWebApp
      description: "POST /api/v2/auth/oauth/telegram\nAuthenticate with Telegram auth code from bot\nBody: { code: string }"
      operationId: authenticateTelegramWebApp
      responses:
        200:
          description: "Operation completed!"
  /auth/oauth/telegram:
    post:
      tags:
        - AuthApiV2
      summary: authenticateTelegram
      operationId: authenticateTelegram
      responses:
        200:
          description: "Operation completed!"
  /auth/refresh:
    post:
      tags:
        - AuthApiV2
      summary: refreshToken
      description: POST /api/v2/auth/refresh\nRefresh access token using refresh token
      operationId: refreshToken
      responses:
        200:
          description: "Operation completed!"
  /auth/me:
    get:
      tags:
        - AuthApiV2
      summary: getCurrentUser
      description: GET /api/v2/auth/me\nGet current authenticated user (requires Bearer token)
      operationId: getCurrentUser
      responses:
        200:
          description: "Operation completed!"
  /auth/logout:
    post:
      tags:
        - AuthApiV2
      summary: logout
      description: "POST /api/v2/auth/logout\nLogout and invalidate tokens\nBody (optional): { refreshToken: string }"
      operationId: logout
      responses:
        200:
          description: "Operation completed!"
  /tests/<testId>:
    get:
      tags:
        - TestsApiV2
      summary: getTest
      description: "GET /api/v2/tests/{testId}\nGet test details by ID"
      operationId: getTest
      parameters:
        - name: testId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /tests/<testId>/results:
    post:
      tags:
        - TestsApiV2
      summary: submitTestResults
      description: "POST /api/v2/tests/{testId}/results\nSubmit test results"
      operationId: submitTestResults
      parameters:
        - name: testId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /tests/<testId>/history:
    get:
      tags:
        - TestsApiV2
      summary: getTestHistory
      description: "GET /api/v2/tests/{testId}/history\nGet test attempt history for the authenticated user\nSupports pagination via query params: ?page=1&limit=20"
      operationId: getTestHistory
      parameters:
        - name: testId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /telegram-bot/random-card:
    get:
      tags:
        - TelegramBotApiV2
      summary: getRandomCard
      description: "GET /api/v2/telegram-bot/random-card\nGet a random card from all available cards"
      operationId: getRandomCard
      responses:
        200:
          description: "Operation completed!"
  /telegram-bot/share/check-limit:
    post:
      tags:
        - TelegramBotApiV2
      summary: checkShareLimit
      description: "POST /api/v2/telegram-bot/share/check-limit\nCheck if user can share today (rate limiting)\nBody: { telegramUserId: string, dailyLimit: number }"
      operationId: checkShareLimit
      responses:
        200:
          description: "Operation completed!"
  /telegram-bot/share/record:
    post:
      tags:
        - TelegramBotApiV2
      summary: recordShareRequest
      description: "POST /api/v2/telegram-bot/share/record\nRecord a share request for a user\nBody: { telegramUserId: string, telegramUsername?: string, sharedCardId?: number }"
      operationId: recordShareRequest
      responses:
        200:
          description: "Operation completed!"
  /telegram-bot/users/info:
    get:
      tags:
        - TelegramBotApiV2
      summary: getUsersInfo
      description: "GET /api/v2/telegram-bot/users/info\nGet user information (for admin commands)\nQuery: ?userId=<id> for specific user, or no query for all users summary"
      operationId: getUsersInfo
      responses:
        200:
          description: "Operation completed!"
  /telegram-bot/words:
    get:
      tags:
        - TelegramBotApiV2
      summary: getWords
      description: "GET /api/v2/telegram-bot/words\nGet all words from all cards\nQuery: ?separator=<string> for custom separator (default: comma)"
      operationId: getWords
      responses:
        200:
          description: "Operation completed!"
  /admin/analytics/dashboard:
    get:
      tags:
        - AdminAnalyticsApiV2
      summary: getDashboardAnalytics
      description: GET /api/v2/admin/analytics/dashboard\nGet dashboard analytics data
      operationId: getDashboardAnalytics
      responses:
        200:
          description: "Operation completed!"
  /admin/analytics/users/chart:
    get:
      tags:
        - AdminAnalyticsApiV2
      summary: getUsersChart
      description: GET /api/v2/admin/analytics/users/chart\nGet user registration chart data for the last 30 days
      operationId: getUsersChart
      responses:
        200:
          description: "Operation completed!"
  /admin/analytics/revenue/chart:
    get:
      tags:
        - AdminAnalyticsApiV2
      summary: getRevenueChart
      description: GET /api/v2/admin/analytics/revenue/chart\nGet revenue chart data for the last 30 days
      operationId: getRevenueChart
      responses:
        200:
          description: "Operation completed!"
  /tasks:
    get:
      tags:
        - TasksApiV2
      summary: "GET /api/v2/tasks - Get tasks with optional filtering"
      operationId: getTasks
      responses:
        200:
          description: "Operation completed!"
  /tasks/<taskId>:
    get:
      tags:
        - TasksApiV2
      summary: "GET /api/v2/tasks/{taskId} - Get specific task"
      operationId: getTask
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /tasks/<taskId>/start:
    post:
      tags:
        - TasksApiV2
      summary: "POST /api/v2/tasks/{taskId}/start - Start a task"
      operationId: startTask
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /tasks/<taskId>/complete:
    post:
      tags:
        - TasksApiV2
      summary: "POST /api/v2/tasks/{taskId}/complete - Complete a task"
      operationId: completeTask
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /users/me/tasks/progress:
    get:
      tags:
        - TasksApiV2
      summary: "GET /api/v2/users/me/tasks/progress - Get user task progress"
      operationId: getUserTaskProgress
      responses:
        200:
          description: "Operation completed!"
  /tasks/categories:
    get:
      tags:
        - TasksApiV2
      summary: "GET /api/v2/tasks/categories - Get task categories"
      operationId: getTaskCategories
      responses:
        200:
          description: "Operation completed!"
components: { }
tags:
  - name: PromocodesApiV2
    description: API v2 endpoints for promocode management and activation.
  - name: DiscountsApiV2
    description: Admin endpoints for discount campaign management.
  - name: AdminCardsApiV2
  - name: SubscriptionsApiV2
    description: "Subscriptions API v2\nRESTful endpoints for managing subscriptions & plans"
  - name: UsersApiV2
    description: "API v2 endpoints for user profile and self-service operations."
  - name: AdminAuthApiV2
    description: Admin authentication API endpoints
  - name: AuthApiV2
    description: API v2 Authentication endpoints\n\nImplements OAuth2/JWT Bearer token authentication
  - name: TestsApiV2
    description: Tests API v2\n\nRESTful endpoints for managing tests and test results
  - name: TelegramBotApiV2
    description: "API v2 endpoints for Telegram Bot\n\nThese endpoints are authenticated via X-API-Key header\nand provide functionality for Telegram bot integration"
  - name: AdminAnalyticsApiV2
    description: Admin endpoints for analytics and statistics in API v2.
  - name: TasksApiV2
    description: API v2 endpoints for user tasks management