basePath: /
definitions:
  models.CanRepeatResponse:
    properties:
      can_repeat:
        type: boolean
      next_available_at:
        type: string
    type: object
  models.CreateOperatorRequest:
    properties:
      name:
        type: string
      telegram_id:
        type: integer
    type: object
  models.DeliveryType:
    enum:
    - physical
    - digital
    type: string
    x-enum-varnames:
    - Physical
    - Digital
  models.GenerateQRCodesRequest:
    properties:
      count:
        description: Number of codes to generate
        type: integer
      type:
        description: e.g., "reward", "quiz"
        type: string
      value:
        description: e.g., "50" for reward, "1" for quiz
        type: string
    type: object
  models.GenerateQRCodesResponse:
    properties:
      tokens:
        description: List of generated unique tokens
        items:
          type: string
        type: array
    type: object
  models.GrantStarsRequest:
    properties:
      amount:
        type: integer
      user_id:
        type: integer
    type: object
  models.Option:
    properties:
      id:
        type: integer
      is_correct:
        type: boolean
      text:
        type: string
    type: object
  models.Purchase:
    properties:
      id:
        type: integer
      purchased_at:
        type: string
      reward_id:
        type: integer
      stars_spent:
        type: integer
      status:
        $ref: '#/definitions/models.PurchaseStatus'
      user_id:
        type: integer
    type: object
  models.PurchaseStatus:
    enum:
    - pending
    - delivered
    - cancelled
    type: string
    x-enum-varnames:
    - Pending
    - Delivered
    - Cancelled
  models.QRValidateRequest:
    properties:
      payload:
        type: string
    type: object
  models.Question:
    properties:
      id:
        type: integer
      options:
        description: Stored as JSONB
        items:
          $ref: '#/definitions/models.Option'
        type: array
      order_index:
        type: integer
      quiz_id:
        type: integer
      text:
        type: string
      type:
        $ref: '#/definitions/models.QuestionType'
    type: object
  models.QuestionType:
    enum:
    - single
    - multiple
    type: string
    x-enum-varnames:
    - Single
    - Multiple
  models.Quiz:
    properties:
      can_repeat:
        type: boolean
      created_at:
        type: string
      created_by:
        type: integer
      description:
        type: string
      has_timer:
        type: boolean
      id:
        type: integer
      image_url:
        type: string
      is_active:
        type: boolean
      questions:
        description: This field is for API responses, not DB storage
        items:
          $ref: '#/definitions/models.Question'
        type: array
      repeat_cooldown_hours:
        type: integer
      reward_stars:
        type: integer
      timer_per_question:
        type: integer
      title:
        type: string
    type: object
  models.Reward:
    properties:
      created_at:
        type: string
      created_by:
        type: integer
      delivery_type:
        $ref: '#/definitions/models.DeliveryType'
      description:
        type: string
      id:
        type: integer
      image_url:
        type: string
      instructions:
        type: string
      is_active:
        type: boolean
      price_stars:
        type: integer
      stock:
        type: integer
      title:
        type: string
    type: object
  models.SubmissionRequest:
    properties:
      answers:
        items:
          $ref: '#/definitions/models.UserAnswer'
        type: array
    type: object
  models.Transaction:
    properties:
      amount:
        type: integer
      created_at:
        type: string
      description:
        type: string
      type:
        $ref: '#/definitions/models.TransactionType'
    type: object
  models.TransactionType:
    enum:
    - earned
    - spent
    type: string
    x-enum-varnames:
    - TransactionEarned
    - TransactionSpent
  models.User:
    properties:
      created_at:
        type: string
      first_name:
        type: string
      last_name:
        type: string
      stars_balance:
        type: integer
      telegram_id:
        type: integer
      username:
        type: string
    type: object
  models.UserAnswer:
    properties:
      option_ids:
        items:
          type: integer
        type: array
      question_id:
        type: integer
    type: object
host: localhost:8080
info:
  contact: {}
  description: API для Telegram Mini App с викторинами, QR-сканированием и внутренней
    валютой
  title: Telegram Quiz Mini App API
  version: "1.0"
paths:
  /api/admin/analytics:
    get:
      consumes:
      - application/json
      description: Returns analytics data including user statistics, rewards, and
        quiz performance (admin/operator only)
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            properties:
              data:
                type: object
              message:
                type: string
              success:
                type: boolean
            type: object
        "500":
          description: Internal Server Error
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Get analytics data
      tags:
      - admin
  /api/admin/operators:
    post:
      consumes:
      - application/json
      description: Creates a new operator account (admin only)
      parameters:
      - description: Create operator request
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/models.CreateOperatorRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "400":
          description: Bad Request
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "500":
          description: Internal Server Error
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Create operator
      tags:
      - admin
  /api/admin/operators/{id}:
    delete:
      consumes:
      - application/json
      description: Deletes an operator account (admin only)
      parameters:
      - description: Operator Telegram ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "400":
          description: Bad Request
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "500":
          description: Internal Server Error
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Delete operator
      tags:
      - admin
  /api/admin/qrcodes:
    post:
      consumes:
      - application/json
      description: Generates unique QR codes for rewards, quizzes, or shop items (admin/operator
        only)
      parameters:
      - description: QR codes generation request
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/models.GenerateQRCodesRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            properties:
              data:
                $ref: '#/definitions/models.GenerateQRCodesResponse'
              message:
                type: string
              success:
                type: boolean
            type: object
        "400":
          description: Bad Request
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "500":
          description: Internal Server Error
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Generate QR codes
      tags:
      - qr
  /api/admin/quizzes:
    post:
      consumes:
      - application/json
      description: Creates a new quiz (admin/operator only)
      parameters:
      - description: Quiz object
        in: body
        name: quiz
        required: true
        schema:
          $ref: '#/definitions/models.Quiz'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            properties:
              data:
                $ref: '#/definitions/models.Quiz'
              message:
                type: string
              success:
                type: boolean
            type: object
        "400":
          description: Bad Request
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "500":
          description: Internal Server Error
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Create a new quiz
      tags:
      - quizzes
  /api/admin/quizzes/{id}:
    delete:
      consumes:
      - application/json
      description: Deletes a quiz (admin only)
      parameters:
      - description: Quiz ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "400":
          description: Bad Request
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "500":
          description: Internal Server Error
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Delete a quiz
      tags:
      - quizzes
    put:
      consumes:
      - application/json
      description: Updates an existing quiz (admin only)
      parameters:
      - description: Quiz ID
        in: path
        name: id
        required: true
        type: integer
      - description: Updated quiz object
        in: body
        name: quiz
        required: true
        schema:
          $ref: '#/definitions/models.Quiz'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            properties:
              data:
                $ref: '#/definitions/models.Quiz'
              message:
                type: string
              success:
                type: boolean
            type: object
        "400":
          description: Bad Request
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "500":
          description: Internal Server Error
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Update a quiz
      tags:
      - quizzes
  /api/admin/quizzes/{quiz_id}/questions:
    post:
      consumes:
      - application/json
      description: Adds a new question to a quiz (admin/operator only)
      parameters:
      - description: Quiz ID
        in: path
        name: quiz_id
        required: true
        type: integer
      - description: Question object
        in: body
        name: question
        required: true
        schema:
          $ref: '#/definitions/models.Question'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            properties:
              data:
                $ref: '#/definitions/models.Question'
              message:
                type: string
              success:
                type: boolean
            type: object
        "400":
          description: Bad Request
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "500":
          description: Internal Server Error
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Create question
      tags:
      - questions
  /api/admin/rewards:
    post:
      consumes:
      - application/json
      description: Creates a new reward that users can purchase with stars (admin/operator
        only)
      parameters:
      - description: Reward object
        in: body
        name: reward
        required: true
        schema:
          $ref: '#/definitions/models.Reward'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            properties:
              data:
                $ref: '#/definitions/models.Reward'
              message:
                type: string
              success:
                type: boolean
            type: object
        "400":
          description: Bad Request
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "500":
          description: Internal Server Error
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Create a new reward
      tags:
      - rewards
  /api/admin/rewards/{id}:
    delete:
      consumes:
      - application/json
      description: Deletes a reward (admin only)
      parameters:
      - description: Reward ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "400":
          description: Bad Request
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "500":
          description: Internal Server Error
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Delete a reward
      tags:
      - rewards
    put:
      consumes:
      - application/json
      description: Updates an existing reward (admin only)
      parameters:
      - description: Reward ID
        in: path
        name: id
        required: true
        type: integer
      - description: Updated reward object
        in: body
        name: reward
        required: true
        schema:
          $ref: '#/definitions/models.Reward'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            properties:
              data:
                $ref: '#/definitions/models.Reward'
              message:
                type: string
              success:
                type: boolean
            type: object
        "400":
          description: Bad Request
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "500":
          description: Internal Server Error
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Update a reward
      tags:
      - rewards
  /api/admin/users/grant-stars:
    post:
      consumes:
      - application/json
      description: Manually grants stars to a user (admin only)
      parameters:
      - description: Grant stars request
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/models.GrantStarsRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "400":
          description: Bad Request
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "500":
          description: Internal Server Error
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Grant stars to user
      tags:
      - admin
  /api/auth/me:
    get:
      consumes:
      - application/json
      description: Returns information about the currently authenticated Telegram
        user
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            properties:
              data:
                type: object
              message:
                type: string
              success:
                type: boolean
            type: object
        "401":
          description: Unauthorized
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Get current authenticated user
      tags:
      - auth
  /api/auth/validate:
    post:
      consumes:
      - application/json
      description: Validates Telegram WebApp init data and returns user information
      parameters:
      - description: Init data validation request
        in: body
        name: request
        required: true
        schema:
          properties:
            initData:
              type: string
          type: object
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            properties:
              data:
                type: object
              message:
                type: string
              success:
                type: boolean
            type: object
        "400":
          description: Bad Request
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "401":
          description: Unauthorized
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      summary: Validate Telegram WebApp init data
      tags:
      - auth
  /api/me:
    get:
      consumes:
      - application/json
      description: Returns the current user's profile information including balance
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            properties:
              data:
                $ref: '#/definitions/models.User'
              message:
                type: string
              success:
                type: boolean
            type: object
        "404":
          description: Not Found
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Get current user profile
      tags:
      - user
  /api/qr/validate:
    post:
      consumes:
      - application/json
      description: Validates a QR code payload and processes the associated action
      parameters:
      - description: QR validation request
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/models.QRValidateRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            properties:
              data:
                type: object
              message:
                type: string
              success:
                type: boolean
            type: object
        "400":
          description: Bad Request
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "401":
          description: Unauthorized
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Validate QR code payload
      tags:
      - qr
  /api/quizzes:
    get:
      consumes:
      - application/json
      description: Returns a list of all active quizzes
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            properties:
              data:
                items:
                  $ref: '#/definitions/models.Quiz'
                type: array
              message:
                type: string
              success:
                type: boolean
            type: object
        "500":
          description: Internal Server Error
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Get all active quizzes
      tags:
      - quizzes
  /api/quizzes/{id}:
    get:
      consumes:
      - application/json
      description: Returns a single quiz with all its questions
      parameters:
      - description: Quiz ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            properties:
              data:
                $ref: '#/definitions/models.Quiz'
              message:
                type: string
              success:
                type: boolean
            type: object
        "400":
          description: Bad Request
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "404":
          description: Not Found
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "500":
          description: Internal Server Error
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Get quiz by ID
      tags:
      - quizzes
  /api/quizzes/{id}/can-repeat:
    get:
      consumes:
      - application/json
      description: Checks if user can repeat a quiz and when it will be available
      parameters:
      - description: Quiz ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            properties:
              data:
                $ref: '#/definitions/models.CanRepeatResponse'
              message:
                type: string
              success:
                type: boolean
            type: object
        "400":
          description: Bad Request
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "500":
          description: Internal Server Error
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Check if quiz can be repeated
      tags:
      - quizzes
  /api/quizzes/{id}/submit:
    post:
      consumes:
      - application/json
      description: Submits quiz answers and calculates score/stars earned
      parameters:
      - description: Quiz ID
        in: path
        name: id
        required: true
        type: integer
      - description: Quiz submission
        in: body
        name: submission
        required: true
        schema:
          $ref: '#/definitions/models.SubmissionRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            properties:
              data:
                type: object
              message:
                type: string
              success:
                type: boolean
            type: object
        "400":
          description: Bad Request
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "500":
          description: Internal Server Error
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Submit quiz answers
      tags:
      - quizzes
  /api/rewards:
    get:
      consumes:
      - application/json
      description: Returns a list of all active rewards available for purchase
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            properties:
              data:
                items:
                  $ref: '#/definitions/models.Reward'
                type: array
              message:
                type: string
              success:
                type: boolean
            type: object
        "500":
          description: Internal Server Error
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Get all active rewards
      tags:
      - rewards
  /api/rewards/{id}/purchase:
    post:
      consumes:
      - application/json
      description: Allows a user to purchase a reward using their stars
      parameters:
      - description: Reward ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            properties:
              data:
                $ref: '#/definitions/models.Purchase'
              message:
                type: string
              success:
                type: boolean
            type: object
        "400":
          description: Bad Request
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
        "500":
          description: Internal Server Error
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Purchase a reward
      tags:
      - rewards
  /api/user/purchases:
    get:
      consumes:
      - application/json
      description: Returns the current user's purchase history
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            properties:
              data:
                items:
                  $ref: '#/definitions/models.Purchase'
                type: array
              message:
                type: string
              success:
                type: boolean
            type: object
        "500":
          description: Internal Server Error
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Get user purchase history
      tags:
      - user
  /api/user/transactions:
    get:
      consumes:
      - application/json
      description: Returns the current user's transaction history (earned/spent stars)
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            properties:
              data:
                items:
                  $ref: '#/definitions/models.Transaction'
                type: array
              message:
                type: string
              success:
                type: boolean
            type: object
        "500":
          description: Internal Server Error
          schema:
            properties:
              message:
                type: string
              success:
                type: boolean
            type: object
      security:
      - ApiKeyAuth: []
      summary: Get user transaction history
      tags:
      - user
securityDefinitions:
  ApiKeyAuth:
    in: header
    name: Authorization
    type: apiKey
  BasicAuth:
    type: basic
swagger: "2.0"