openapi: 3.1.0
info:
  title: AI2N Tools API
  version: 1.0.0
  description: "API для инструментов tools.ai2n.dev: типограф, генератор красивых паролей и помидор-таймер."
servers:
  - url: https://tools.ai2n.dev
    description: Production
  - url: http://127.0.0.1:97
    description: Local production port
tags:
  - name: System
  - name: Tools
  - name: Typograph
  - name: Password
  - name: Pomodoro
paths:
  /health:
    get:
      tags: [System]
      summary: Проверка статуса сервиса
      responses:
        "200":
          description: Сервис работает
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Health"
  /api/tools:
    get:
      tags: [Tools]
      summary: Каталог доступных инструментов
      responses:
        "200":
          description: Список инструментов с web и API маршрутами
          content:
            application/json:
              schema:
                type: object
                properties:
                  tools:
                    type: array
                    items:
                      $ref: "#/components/schemas/Tool"
  /api/health:
    get:
      tags: [System]
      summary: Проверка статуса tools.ai2n.dev через API-роут
      responses:
        "200":
          description: Сервис tools.ai2n.dev работает
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Health"
  /api/typograph/rules:
    get:
      tags: [Typograph]
      summary: Каталог правил типографа
      responses:
        "200":
          description: Группы и правила типографа
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    example: 130
                  groups:
                    type: array
                    items:
                      $ref: "#/components/schemas/TypographGroup"
                  rules:
                    type: array
                    items:
                      $ref: "#/components/schemas/TypographRule"
  /api/typograph:
    post:
      tags: [Typograph]
      summary: Применить типограф к тексту
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TypographRequest"
            examples:
              default:
                value:
                  text: "\"Привет\" - это 100 % тест..."
                  options:
                    quotes: true
                    dashes: true
                    units: true
      responses:
        "200":
          description: Отформатированный текст и список примененных правил
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TypographResponse"
  /api/password:
    post:
      tags: [Password]
      summary: Сгенерировать красивые пароли из слов, цифр и символов
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PasswordRequest"
            examples:
              default:
                value:
                  options:
                    count: 8
                    wordsCount: 3
                    language: mixed
                    separator: "-"
                    addNumber: true
                    addSymbol: true
      responses:
        "200":
          description: Варианты паролей и оценка энтропии
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PasswordResponse"
  /api/pomodoro/presets:
    get:
      tags: [Pomodoro]
      summary: Список пресетов помидор-таймера
      responses:
        "200":
          description: Доступные режимы фокусировки
          content:
            application/json:
              schema:
                type: object
                properties:
                  presets:
                    type: array
                    items:
                      $ref: "#/components/schemas/PomodoroPreset"
  /api/pomodoro/session:
    post:
      tags: [Pomodoro]
      summary: Построить план pomodoro-сессии
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PomodoroRequest"
      responses:
        "200":
          description: Таймлайн фокус-блоков и перерывов
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PomodoroSession"
components:
  schemas:
    Health:
      type: object
      properties:
        ok:
          type: boolean
        service:
          type: string
          example: tools.ai2n.dev
        port:
          type: integer
          example: 97
        tools:
          type: integer
          example: 3
        typographRules:
          type: integer
          example: 130
        openapi:
          type: string
          example: /openapi.yml
    Tool:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        href:
          type: string
        api:
          type: string
        description:
          type: string
        stats:
          type: string
    TypographGroup:
      type: object
      properties:
        key:
          type: string
        label:
          type: string
        description:
          type: string
    TypographRule:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        group:
          type: string
        enabledByDefault:
          type: boolean
    TypographRequest:
      type: object
      required: [text]
      properties:
        text:
          type: string
        options:
          type: object
          properties:
            cleanup:
              type: boolean
            spacing:
              type: boolean
            punctuation:
              type: boolean
            quotes:
              type: boolean
            dashes:
              type: boolean
            symbols:
              type: boolean
            units:
              type: boolean
            abbreviations:
              type: boolean
            seo:
              type: boolean
    TypographResponse:
      type: object
      properties:
        text:
          type: string
        sourceLength:
          type: integer
        resultLength:
          type: integer
        changed:
          type: boolean
        rulesTotal:
          type: integer
        appliedRules:
          type: array
          items:
            $ref: "#/components/schemas/TypographRule"
        stats:
          type: object
          properties:
            paragraphs:
              type: integer
            words:
              type: integer
            characters:
              type: integer
    PasswordRequest:
      type: object
      properties:
        options:
          type: object
          properties:
            count:
              type: integer
              minimum: 1
              maximum: 24
            charLength:
              type: integer
              minimum: 6
              maximum: 30
            wordsCount:
              type: integer
              minimum: 2
              maximum: 6
            language:
              type: string
              enum: [ru, en, mixed]
            separator:
              type: string
            capitalize:
              type: boolean
            addNumber:
              type: boolean
            addSymbol:
              type: boolean
            digits:
              type: integer
              minimum: 1
              maximum: 6
    PasswordResponse:
      type: object
      properties:
        passwords:
          type: array
          items:
            type: string
        entropyBits:
          type: number
        score:
          type: string
        dictionarySize:
          type: integer
    PomodoroPreset:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        focusMinutes:
          type: integer
        shortBreakMinutes:
          type: integer
        longBreakMinutes:
          type: integer
        rounds:
          type: integer
        longBreakEvery:
          type: integer
    PomodoroRequest:
      type: object
      properties:
        options:
          type: object
          properties:
            preset:
              type: string
            focusMinutes:
              type: integer
            shortBreakMinutes:
              type: integer
            longBreakMinutes:
              type: integer
            rounds:
              type: integer
            longBreakEvery:
              type: integer
            startAt:
              type: string
              format: date-time
    PomodoroSession:
      type: object
      properties:
        preset:
          type: string
        timeline:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              type:
                type: string
                enum: [focus, short-break, long-break]
              label:
                type: string
              minutes:
                type: integer
              startsAt:
                type: string
                format: date-time
              endsAt:
                type: string
                format: date-time
        totals:
          type: object
          properties:
            focusMinutes:
              type: integer
            breakMinutes:
              type: integer
            totalMinutes:
              type: integer
            blocks:
              type: integer
