meta {
  name: Get Popular Books
  type: http
  seq: 1
}

get {
  url: {{base_url}}/api/analytics/popular-books?limit=10
  body: none
  auth: inherit
}

tests {
  test("status must be 200", function() {
    expect(res.status).to.eql(200);
  });

  test("response has books array", function() {
    const body = JSON.parse(res.body);
    expect(body).to.have.property("books");
    expect(body.books).to.be.an("array");
  });

  test("books have required fields", function() {
    const body = JSON.parse(res.body);
    if (body.books.length > 0) {
      expect(body.books[0]).to.have.property("title");
      expect(body.books[0]).to.have.property("author");
      expect(body.books[0]).to.have.property("read_count");
      expect(body.books[0]).to.have.property("avg_completion");
    }
  });
}

settings {
  encodeUrl: true
  timeout: 0
}

docs {
  Get popular books sorted by read count.

  **Endpoint**: GET /api/analytics/popular-books
  **Auth**: Required (Bearer token)

  ## Query Parameters

  | Parameter | Type | Required | Description |
  |-----------|------|-----------|-------------|
  | limit | int | No | Maximum number of books to return (default: 10) |

  ## Response Fields

  | Field | Type | Description |
  |-------|------|-------------|
  | books | array | List of popular books |
  | books[].media_item_id | string | Book ID |
  | books[].title | string | Book title |
  | books[].author | string | Book author |
  | books[].read_count | int | Number of times read |
  | books[].avg_completion | float | Average completion rate (0-1) |
  | books[].cover_url | string | Cover image URL |

  ## Example Request

  ```
  GET /api/analytics/popular-books?limit=10
  ```

  ## Example Response

  ```json
  {
    "books": [
      {
        "media_item_id": "323e4567-e89b-12d3-a456-426614174002",
        "title": "The Great Gatsby",
        "author": "F. Scott Fitzgerald",
        "read_count": 5,
        "avg_completion": 0.85,
        "cover_url": "/api/books/323e4567-e89b-12d3-a456-426614174002/cover"
      }
    ]
  }
  ```

  ## Error Responses

  | Code | Description |
  |------|-------------|
  | 401 | Unauthorized |
  | 500 | Internal server error |

  ## Notes

  - Books are sorted by read_count in descending order
  - Only books owned by the authenticated user are included
  - avg_completion is calculated from all reading sessions
}