openapi.yaml

openapi: 3.0.3
info:
  title: EMS Questions API
  version: 1.0.0
  description: |
    API for product, question, checkout, and user management for the EMS Questions App.
servers:
  - url: /api
paths:
  /admin/questions/{id}:
    get:
      summary: Get a question by ID
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Question found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Question"
        "400":
          description: Missing question ID
        "404":
          description: Question not found
    put:
      summary: Update a question
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QuestionUpdate"
      responses:
        "200":
          description: Question updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Question"
        "400":
          description: Invalid question data
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        "404":
          description: Question not found
    delete:
      summary: Delete a question
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Question deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        "400":
          description: Missing question ID
        "404":
          description: Question not found
        "500":
          description: Server error
  /admin/question:
    get:
      summary: Generate a question (based on prompt and optional chapter)
      parameters:
        - in: query
          name: prompt
          required: true
          schema:
            type: string
        - in: query
          name: chapterId
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Generated question
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Question"
        "400":
          description: Missing parameters or error generating question
    post:
      summary: Create a new question
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QuestionCreate"
      responses:
        "200":
          description: Question created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Question"
        "400":
          description: Invalid question data
  /admin/product:
    post:
      summary: Import a product from Printful
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [printful_id]
              properties:
                printful_id:
                  type: string
      responses:
        "200":
          description: Product imported
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  product:
                    $ref: "#/components/schemas/Product"
        "400":
          description: Missing printful_id
        "404":
          description: Product not found in Printful
  /admin/product/{id}:
    put:
      summary: Update a product
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProductUpdate"
      responses:
        "200":
          description: Product updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  product:
                    $ref: "#/components/schemas/Product"
        "404":
          description: Product not found
    delete:
      summary: Delete a product
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Product deleted
        "404":
          description: Product not found
  /admin/questions/report/resolve:
    post:
      summary: Resolve a question report
      description: Marks a question report as resolved by setting the resolved_at timestamp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResolveReportRequest"
      responses:
        "200":
          description: Report successfully resolved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        "400":
          description: Invalid request format
        "500":
          description: Internal server error
  /admin/product/{id}/toggle-active:
    post:
      summary: Toggle product active status
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Product status toggled
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  product:
                    $ref: "#/components/schemas/Product"
        "404":
          description: Product not found
  /admin/product/{id}/variants:
    get:
      summary: List variants for a product
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: List of variants
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  variants:
                    type: array
                    items:
                      $ref: "#/components/schemas/ProductVariant"
  /admin/product/{id}/variant/{variant_id}:
    put:
      summary: Update or create a product variant
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: variant_id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProductVariantUpdate"
      responses:
        "200":
          description: Variant updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  variant:
                    $ref: "#/components/schemas/ProductVariant"
        "404":
          description: Product or variant not found
    delete:
      summary: Delete a product variant (deactivates all Stripe prices, deletes Stripe product, and removes from database)
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: variant_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Variant deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        "400":
          description: Bad request (missing IDs or stripe_product_id)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        "404":
          description: Variant not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        "500":
          description: Internal error (Stripe or DB failure)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  details:
                    type: string

      summary: Update or create a product variant
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: variant_id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProductVariantUpdate"
      responses:
        "200":
          description: Variant updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  variant:
                    $ref: "#/components/schemas/ProductVariant"
        "404":
          description: Product or variant not found
  /admin/question:
    get:
      summary: Generate a new question from OpenAI
      parameters:
        - name: prompt
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Generated question
    post:
      summary: Create a new question
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QuestionCreate"
      responses:
        "200":
          description: Question created
  /checkout:
    post:
      summary: Create Stripe checkout session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CheckoutRequest"
      responses:
        "200":
          description: Stripe checkout session created
        "400":
          description: Invalid request body
  /preferences:
    post:
      summary: Update user theme preference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                theme:
                  type: string
                  enum: [light, dark]
      responses:
        "200":
          description: Preferences updated
  /profile:
    patch:
      summary: Update user profile display name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                display_name:
                  type: string
      responses:
        "200":
          description: User updated
  /question:
    get:
      summary: Get a random question
      responses:
        "200":
          description: Random question
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Question"
    post:
      summary: Submit an answer to a question
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [questionId, answer]
              properties:
                questionId:
                  type: string
                answer:
                  type: string
      responses:
        "200":
          description: Answer result
          content:
            application/json:
              schema:
                type: object
                properties:
                  question:
                    $ref: "#/components/schemas/Question"
                  correct:
                    type: boolean
                  selectedAnswer:
                    type: string
                  streak:
                    $ref: "#/components/schemas/Streak"
  /stripe_webhook:
    post:
      summary: Stripe webhook for payment events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Webhook received
  /support:
    post:
      summary: Submit a support or feedback request
      description: Allows users to contact the site admin with questions, feedback, or issue reports
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/SupportRequest"
      responses:
        "302":
          description: Redirect to support page with success or error message
          headers:
            Location:
              schema:
                type: string
              description: URL to redirect to
components:
  schemas:
    Question:
      type: object
      properties:
        id:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        question:
          type: string
        choices:
          type: array
          items:
            type: string
        correct_answer:
          type: number
        explanation:
          type: string
        category:
          type: string
        scope:
          type: string
          enum: [emt, advanced, medic]
    QuestionCreate:
      type: object
      required:
        - question
        - choices
        - correct_answer
        - explanation
        - category
      properties:
        question:
          type: string
        choices:
          type: array
          items:
            type: string
        correct_answer:
          type: number
        explanation:
          type: string
        category:
          type: string
    QuestionUpdate:
      type: object
      properties:
        question:
          type: string
        choices:
          type: array
          items:
            type: string
        correct_answer:
          type: number
        explanation:
          type: string
        category:
          type: string
    Product:
      type: object
      properties:
        printful_id:
          type: string
        product_template_id:
          type: string
        name:
          type: string
        thumbnail_url:
          type: string
        description:
          type: string
        price:
          type: number
        active:
          type: boolean
        colors:
          type: array
          items:
            type: string
    ProductUpdate:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        price:
          type: number
        active:
          type: boolean
        colors:
          type: array
          items:
            type: string
    ProductVariant:
      type: object
      properties:
        variant_id:
          type: string
        color:
          type: string
        size:
          type: string
        price:
          type: number
        images:
          type: array
          items:
            type: string
    ProductVariantUpdate:
      type: object
      properties:
        color:
          type: string
        size:
          type: string
        price:
          type: number
        images:
          type: array
          items:
            type: string
    Question:
      type: object
      properties:
        id:
          type: string
        question:
          type: string
        choices:
          type: array
          items:
            type: string
        correct_answer:
          type: string
        explanation:
          type: string
        category:
          type: string
    QuestionCreate:
      type: object
      required:
        - question
        - choices
        - correct_answer
        - explanation
        - category
      properties:
        question:
          type: string
        choices:
          type: array
          items:
            type: string
        correct_answer:
          type: string
        explanation:
          type: string
        category:
          type: string
    CheckoutRequest:
      type: object
      properties:
        cartItems:
          type: array
          items:
            type: object
            properties:
              variant:
                $ref: "#/components/schemas/ProductVariant"
              quantity:
                type: integer
    Streak:
      type: object
      properties:
        days:
          type: integer
    ResolveReportRequest:
      type: object
      required:
        - questionId
        - reportId
      properties:
        questionId:
          type: string
          description: ID of the question that was reported
        reportId:
          type: string
          description: ID of the report to resolve
    SupportRequest:
      type: object
      required:
        - name
        - email
        - subject
        - message
      properties:
        name:
          type: string
          description: The name of the person submitting the support request
        email:
          type: string
          format: email
          description: The email address for contact/reply
        subject:
          type: string
          description: The subject of the support request
        message:
          type: string
          description: The detailed message content explaining the issue or feedback