openapi: 3.0.0
info:
  title: Api
  version: 0.0.0
servers:
  - url: "http://localhost:8080"
paths:
  /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!"
  /ads/product/acquire/<key>:
    post:
      tags:
        - AdsApiV2
      summary: "POST /api/v2/ads/product/acquire/{key}"
      description: Confirms rewarded ad completion and grants product access to the user.
      operationId: acquireProductForAd
      parameters:
        - name: key
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /adsgram/reward:
    get:
      tags:
        - AdsApiV2
      summary: "GET /api/v2/adsgram/reward?userId={userId}"
      description: Callback endpoint for Adsgram rewarded ad completion.\nThis endpoint is called by Adsgram when a user completes a rewarded ad.
      operationId: adsgramRewardCallback
      responses:
        200:
          description: "Operation completed!"
  /subscriptions/plans:
    get:
      tags:
        - SubscriptionsApiV2
      summary: getPlans
      description: GET /api/v2/subscriptions/plans\nList available subscription plans
      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/users:
    get:
      tags:
        - AdminUsersApiV2
      summary: getUsers
      description: GET /api/v2/admin/users\nReturns list of users by optional ids.
      operationId: getUsers
      responses:
        200:
          description: "Operation completed!"
    post:
      tags:
        - AdminUsersApiV2
      summary: upsertUser
      description: POST /api/v2/admin/users\nCreates or updates user data (admin editing).
      operationId: upsertUser
      responses:
        200:
          description: "Operation completed!"
  /admin/users/ids:
    get:
      tags:
        - AdminUsersApiV2
      summary: getUserIds
      description: GET /api/v2/admin/users/ids\nReturns comma separated user ids.
      operationId: getUserIds
      responses:
        200:
          description: "Operation completed!"
  /admin/users/<userId>/purchases:
    get:
      tags:
        - AdminUsersApiV2
      summary: getUserPurchases
      description: "GET /api/v2/admin/users/<id>/purchases\nReturns user payments history."
      operationId: getUserPurchases
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /admin/users/<userId>:
    delete:
      tags:
        - AdminUsersApiV2
      summary: deleteUser
      description: "DELETE /api/v2/admin/users/<id>\nDeletes user."
      operationId: deleteUser
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /games:
    get:
      tags:
        - GamesApiV2
      summary: getGames
      description: GET /api/v2/games\nGet all available games\nReturns list of games with metadata
      operationId: getGames
      responses:
        200:
          description: "Operation completed!"
  /games/<gameId>/assets:
    get:
      tags:
        - GamesApiV2
      summary: getGameAssets
      description: "GET /api/v2/games/{gameId}/assets\nGet game assets\nReturns game assets file (zip) or asset info"
      operationId: getGameAssets
      parameters:
        - name: gameId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /packs:
    get:
      tags:
        - PacksApiV2
      summary: getPacks
      description: "GET /api/v2/packs\nGet all pack previews with pagination\nQuery params: ?search=term&language=lang&page=1&limit=20"
      operationId: getPacks
      responses:
        200:
          description: "Operation completed!"
  /packs/<packId>:
    get:
      tags:
        - PacksApiV2
      summary: getPack
      description: "GET /api/v2/packs/{packId}\nGet pack details by ID\nReturns full pack details with purchase status if authenticated"
      operationId: getPack
      parameters:
        - name: packId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /packs/<packId>/buy:
    get:
      tags:
        - PacksApiV2
      summary: getPackBuyPage
      description: "GET /api/v2/packs/{packId}/buy\nReturns pack purchase details (includes rewarded ads offer when available)"
      operationId: getPackBuyPage
      parameters:
        - name: packId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /packs/<packId>/cards:
    get:
      tags:
        - PacksApiV2
      summary: getPackCards
      description: "GET /api/v2/packs/{packId}/cards\nGet all cards in a pack\nSupports pagination via query params: ?page=1&limit=20"
      operationId: getPackCards
      parameters:
        - name: packId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /packs/<packId>/cards/<cardId>/image:
    get:
      tags:
        - PacksApiV2
      summary: getCardImage
      description: "GET /api/v2/packs/{packId}/cards/{cardId}/image\nGet card image\nReturns PNG image file\n\nImages are accessible for enabled packs even without authentication\nto allow image preview in public pack listings"
      operationId: getCardImage
      parameters:
        - name: packId
          in: path
          required: true
          schema:
            type: string
        - name: cardId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /packs/<packId>/tests:
    get:
      tags:
        - PacksApiV2
      summary: getPackTests
      description: "GET /api/v2/packs/{packId}/tests\nGet tests for a pack"
      operationId: getPackTests
      parameters:
        - name: packId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /purchases/packs/<packId>:
    post:
      tags:
        - PurchasesApiV2
      summary: createPackPurchase
      description: "POST /api/v2/purchases/packs/{packId}\nCreate purchase intent for a pack\nReturns purchase info including payment URL for YooKassa"
      operationId: createPackPurchase
      parameters:
        - name: packId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /purchases/packs/<packId>/status:
    get:
      tags:
        - PurchasesApiV2
      summary: getPackPurchaseStatus
      description: "GET /api/v2/purchases/packs/{packId}/status\nCheck if pack is purchased by the authenticated user"
      operationId: getPackPurchaseStatus
      parameters:
        - name: packId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Operation completed!"
  /purchases/payments:
    post:
      tags:
        - PurchasesApiV2
      summary: createPayment
      description: POST /api/v2/purchases/payments\nCreate a payment\nCurrently supports YooKassa for web payments
      operationId: createPayment
      responses:
        200:
          description: "Operation completed!"
  /purchases/payments/<paymentId>/verify:
    get:
      tags:
        - PurchasesApiV2
      summary: verifyPayment
      description: "GET /api/v2/purchases/payments/{paymentId}/verify\nVerify payment status\nUpdates user purchases on success"
      operationId: verifyPayment
      parameters:
        - name: paymentId
          in: path
          required: true
          schema:
            type: string
      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/oauth/telegram:
    post:
      tags:
        - AuthApiV2
      summary: authenticateTelegram
      description: "POST /api/v2/auth/oauth/telegram\nAuthenticate with Telegram auth code from bot\nBody: { code: string }"
      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!"
  /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: getUserProgress
      responses:
        200:
          description: "Operation completed!"
  /tasks/categories:
    get:
      tags:
        - TasksApiV2
      summary: "GET /api/v2/tasks/categories - Get available task categories and filters"
      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: AdsApiV2
    description: API v2 endpoints for rewarded ads flows.
  - 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: AdminUsersApiV2
    description: Admin endpoints for user management in API v2.
  - name: GamesApiV2
    description: Games API v2\n\nRESTful endpoints for managing games and game assets
  - name: PacksApiV2
    description: API v2 Packs endpoints\n\nRESTful endpoints for card packs with pagination and filtering
  - name: PurchasesApiV2
    description: Purchases API v2\n\nRESTful endpoints for managing purchases and payments
  - 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: TasksApiV2
    description: API v2 endpoints for user tasks management