openapi: 3.1.0
info:
  title: MeetLog Public Export API
  version: "1.0.0"
  description: |
    Программный доступ к данным пользователя — транскрипциям, отчётам и проектам.
    Аутентификация — личный API-ключ, выпускаемый в настройках аккаунта.

    Базовый URL: `https://meetlog.ru`. Передавайте `Authorization: Bearer <ваш_ключ>`.

    Каждый ключ выпускается с набором scopes (`export:transcripts`, `export:reports`,
    `export:projects`). Для каждого эндпойнта указан требуемый scope.

    Лимит — 60 запросов в минуту на ключ. При исчерпании сервер вернёт `429` с заголовком `Retry-After`.
servers:
  - url: https://meetlog.ru
    description: Production
  - url: http://localhost:8080
    description: Local

security:
  - ApiKeyAuth: []

paths:
  /api/v1/export/transcripts:
    get:
      summary: List transcripts
      description: Страница транскрипций пользователя. Требуется scope `export:transcripts`.
      security:
        - ApiKeyAuth: ["export:transcripts"]
      parameters:
        - in: query
          name: page
          schema: { type: integer, minimum: 1, default: 1 }
        - in: query
          name: page_size
          schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/TranscriptsList" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /api/v1/export/transcripts/{id}:
    get:
      summary: Get transcript
      description: Полная транскрипция с текстом и идентификаторами связанных отчётов. Требуется scope `export:transcripts`.
      security:
        - ApiKeyAuth: ["export:transcripts"]
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/TranscriptDetail" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /api/v1/export/reports:
    get:
      summary: List reports
      description: Все отчёты пользователя со статусом и `transcription_id`. Требуется scope `export:reports`.
      security:
        - ApiKeyAuth: ["export:reports"]
      parameters:
        - in: query
          name: page
          schema: { type: integer, minimum: 1, default: 1 }
        - in: query
          name: page_size
          schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ReportsList" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }

  /api/v1/export/reports/{id}:
    get:
      summary: Get report
      description: Содержимое одного отчёта (поле `content`). Требуется scope `export:reports`.
      security:
        - ApiKeyAuth: ["export:reports"]
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ReportDetail" }
        "404": { $ref: "#/components/responses/NotFound" }

  /api/v1/export/projects:
    get:
      summary: List projects
      description: Список проектов пользователя. Требуется scope `export:projects`.
      security:
        - ApiKeyAuth: ["export:projects"]
      parameters:
        - in: query
          name: page
          schema: { type: integer, minimum: 1, default: 1 }
        - in: query
          name: page_size
          schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ProjectsList" }

  /api/v1/export/projects/{id}:
    get:
      summary: Get project
      description: Проект и список вложенных транскрипций. Требуется scope `export:projects`.
      security:
        - ApiKeyAuth: ["export:projects"]
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ProjectDetail" }
        "404": { $ref: "#/components/responses/NotFound" }

components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: tk_live_*

  responses:
    Unauthorized:
      description: Bad or revoked API key
      content:
        application/json:
          schema: { $ref: "#/components/schemas/ApiError" }
    Forbidden:
      description: Missing scope or wrong endpoint for the key
      content:
        application/json:
          schema: { $ref: "#/components/schemas/ApiError" }
    NotFound:
      description: Resource not found or does not belong to the API key owner
      content:
        application/json:
          schema: { $ref: "#/components/schemas/ApiError" }
    RateLimited:
      description: 60 req/min per key exceeded; Retry-After header is set
      content:
        application/json:
          schema: { $ref: "#/components/schemas/ApiError" }

  schemas:
    PageMeta:
      type: object
      required: [page, page_size, total, total_pages]
      properties:
        page: { type: integer, example: 1 }
        page_size: { type: integer, example: 50 }
        total: { type: integer, example: 137 }
        total_pages: { type: integer, example: 3 }

    TranscriptSummary:
      type: object
      required: [id, status, created_at]
      properties:
        id: { type: string }
        title: { type: string, nullable: true }
        status:
          type: string
          enum: [pending, processing, recording, completed, incomplete, failed]
        created_at: { type: string, format: date-time }
        duration_seconds: { type: integer, nullable: true }
        source_url: { type: string, nullable: true }

    TranscriptDetail:
      allOf:
        - $ref: "#/components/schemas/TranscriptSummary"
        - type: object
          properties:
            text: { type: string, nullable: true }
            summary: { type: string, nullable: true }
            file_size_mb: { type: number, nullable: true }
            report_ids:
              type: array
              items: { type: string }

    TranscriptsList:
      type: object
      required: [items, meta]
      properties:
        items:
          type: array
          items: { $ref: "#/components/schemas/TranscriptSummary" }
        meta: { $ref: "#/components/schemas/PageMeta" }

    ReportSummary:
      type: object
      required: [id, transcription_id, template_name, status, is_auto_generated, created_at]
      properties:
        id: { type: string }
        transcription_id: { type: string }
        template_name: { type: string }
        template_code: { type: string, nullable: true }
        status:
          type: string
          enum: [pending, processing, completed, failed]
        is_auto_generated: { type: boolean }
        created_at: { type: string, format: date-time }

    ReportDetail:
      allOf:
        - $ref: "#/components/schemas/ReportSummary"
        - type: object
          properties:
            content: { type: string, nullable: true }

    ReportsList:
      type: object
      required: [items, meta]
      properties:
        items:
          type: array
          items: { $ref: "#/components/schemas/ReportSummary" }
        meta: { $ref: "#/components/schemas/PageMeta" }

    ProjectSummary:
      type: object
      required: [id, name, created_at, updated_at]
      properties:
        id: { type: string }
        name: { type: string }
        description: { type: string, nullable: true }
        color: { type: string, nullable: true }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    ProjectDetail:
      allOf:
        - $ref: "#/components/schemas/ProjectSummary"
        - type: object
          properties:
            transcripts:
              type: array
              items: { $ref: "#/components/schemas/TranscriptSummary" }

    ProjectsList:
      type: object
      required: [items, meta]
      properties:
        items:
          type: array
          items: { $ref: "#/components/schemas/ProjectSummary" }
        meta: { $ref: "#/components/schemas/PageMeta" }

    ApiError:
      type: object
      properties:
        error_code: { type: string }
        error_message: { type: string }
        status_code: { type: integer }
