Adds methods to GHRepository to get the top ten referral paths and re…

…ferrers via the API (#1770)

* Add methods to get the referral and referrer metrics

* Add links

* Apply code style

* Add methods to get the referral and referrer metrics

* Add links

* Apply code style

* Fix link tags

* Fix javadocs

* Make this work

* Fix format

* Enhance test coverage

* Use hamcrest matchers

* Clear formatting

* Add javadoc to test classes

* Avoid pagination when not required

* Add testcases for methods

* Add javadoc to test methods

* Use java.util.Arrays

---------

Co-authored-by: Liam Newman <bitwiseman@gmail.com>

src/main/java/org/kohsuke/github/GHRepository.java

@@ -41,6 +41,7 @@
 import java.net.URL;
 import java.util.AbstractSet;
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.Collection;
 import java.util.Collections;
 import java.util.Date;
@@ -3618,6 +3619,36 @@ public void unstar() throws IOException {
         root().createRequest().method("DELETE").withUrlPath(String.format("/user/starred/%s", full_name)).send();
     }
 
+    /**
+     * Get the top 10 popular contents over the last 14 days as described on
+     * https://docs.github.com/en/rest/metrics/traffic?apiVersion=2022-11-28#get-top-referral-paths
+     *
+     * @return list of top referral paths
+     * @throws IOException
+     *             the io exception
+     */
+    public List<GHRepositoryTrafficTopReferralPath> getTopReferralPaths() throws IOException {
+        return Arrays.asList(root().createRequest()
+                .method("GET")
+                .withUrlPath(getApiTailUrl("/traffic/popular/paths"))
+                .fetch(GHRepositoryTrafficTopReferralPath[].class));
+    }
+
+    /**
+     * Get the top 10 referrers over the last 14 days as described on
+     * https://docs.github.com/en/rest/metrics/traffic?apiVersion=2022-11-28#get-top-referral-sources
+     *
+     * @return list of top referrers
+     * @throws IOException
+     *             the io exception
+     */
+    public List<GHRepositoryTrafficTopReferralSources> getTopReferralSources() throws IOException {
+        return Arrays.asList(root().createRequest()
+                .method("GET")
+                .withUrlPath(getApiTailUrl("/traffic/popular/referrers"))
+                .fetch(GHRepositoryTrafficTopReferralSources[].class));
+    }
+
     /**
      * A {@link GHRepositoryBuilder} that allows multiple properties to be updated per request.
      *

src/main/java/org/kohsuke/github/GHRepositoryTrafficReferralBase.java

@@ -0,0 +1,46 @@
+package org.kohsuke.github;
+
+/**
+ * Base class for traffic referral objects.
+ */
+public class GHRepositoryTrafficReferralBase {
+    private int count;
+    private int uniques;
+
+    /**
+     * Instantiates a new Gh repository traffic referral base.
+     */
+    GHRepositoryTrafficReferralBase() {
+    }
+
+    /**
+     * Instantiates a new Gh repository traffic referral base.
+     *
+     * @param count
+     *            the count
+     * @param uniques
+     *            the uniques
+     */
+    GHRepositoryTrafficReferralBase(int count, int uniques) {
+        this.count = count;
+        this.uniques = uniques;
+    }
+
+    /**
+     * Gets count.
+     *
+     * @return the count
+     */
+    public int getCount() {
+        return this.count;
+    }
+
+    /**
+     * Gets uniques.
+     *
+     * @return the uniques
+     */
+    public int getUniques() {
+        return this.uniques;
+    }
+}

src/main/java/org/kohsuke/github/GHRepositoryTrafficTopReferralPath.java

@@ -0,0 +1,51 @@
+package org.kohsuke.github;
+
+/**
+ * Top referral path object.
+ */
+public class GHRepositoryTrafficTopReferralPath extends GHRepositoryTrafficReferralBase {
+    private String path;
+    private String title;
+
+    /**
+     * Instantiates a new Gh repository traffic top referral path.
+     */
+    GHRepositoryTrafficTopReferralPath() {
+    }
+
+    /**
+     * Instantiates a new Gh repository traffic top referral path.
+     *
+     * @param count
+     *            the count
+     * @param uniques
+     *            the uniques
+     * @param path
+     *            the path
+     * @param title
+     *            the title
+     */
+    GHRepositoryTrafficTopReferralPath(int count, int uniques, String path, String title) {
+        super(count, uniques);
+        this.path = path;
+        this.title = title;
+    }
+
+    /**
+     * Gets path.
+     *
+     * @return the path
+     */
+    public String getPath() {
+        return this.path;
+    }
+
+    /**
+     * Gets title.
+     *
+     * @return the title
+     */
+    public String getTitle() {
+        return this.title;
+    }
+}

src/main/java/org/kohsuke/github/GHRepositoryTrafficTopReferralSources.java

@@ -0,0 +1,38 @@
+package org.kohsuke.github;
+
+/**
+ * Top referral source object.
+ */
+public class GHRepositoryTrafficTopReferralSources extends GHRepositoryTrafficReferralBase {
+    private String referrer;
+
+    /**
+     * Instantiates a new Gh repository traffic top referral sources.
+     */
+    GHRepositoryTrafficTopReferralSources() {
+    }
+
+    /**
+     * Instantiates a new Gh repository traffic top referral sources.
+     *
+     * @param count
+     *            the count
+     * @param uniques
+     *            the uniques
+     * @param referrer
+     *            the referrer
+     */
+    GHRepositoryTrafficTopReferralSources(int count, int uniques, String referrer) {
+        super(count, uniques);
+        this.referrer = referrer;
+    }
+
+    /**
+     * Gets referrer.
+     *
+     * @return the referrer
+     */
+    public String getReferrer() {
+        return this.referrer;
+    }
+}

src/test/java/org/kohsuke/github/GHRepositoryTest.java

@@ -1823,6 +1823,32 @@ public void testSearchPullRequests() throws Exception {
         this.verifySingleResult(searchResult, mergedPR);
     }
 
+    /**
+     * Test getTopReferralPaths.
+     *
+     * @throws Exception
+     *             the exception
+     */
+    @Test
+    public void testGetTopReferralPaths() throws Exception {
+        GHRepository repository = gitHub.getRepository("ihrigb/node-doorbird");
+        List<GHRepositoryTrafficTopReferralPath> referralPaths = repository.getTopReferralPaths();
+        assertThat(referralPaths.size(), greaterThan(0));
+    }
+
+    /**
+     * Test getTopReferralSources.
+     *
+     * @throws Exception
+     *             the exception
+     */
+    @Test
+    public void testGetTopReferralSources() throws Exception {
+        GHRepository repository = gitHub.getRepository("ihrigb/node-doorbird");
+        List<GHRepositoryTrafficTopReferralSources> referralSources = repository.getTopReferralSources();
+        assertThat(referralSources.size(), greaterThan(0));
+    }
+
     private void verifyEmptyResult(PagedSearchIterable<GHPullRequest> searchResult) {
         assertThat(searchResult.getTotalCount(), is(0));
     }

src/test/java/org/kohsuke/github/GHRepositoryTrafficReferralBaseTest.java

@@ -0,0 +1,23 @@
+package org.kohsuke.github;
+
+import org.junit.Test;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.Matchers.is;
+
+/**
+ * Unit test for {@link GHRepositoryTrafficReferralBase}.
+ */
+public class GHRepositoryTrafficReferralBaseTest {
+
+    /**
+     * Test the constructor.
+     */
+    @Test
+    public void test() {
+        GHRepositoryTrafficReferralBase testee = new GHRepositoryTrafficReferralBase(1, 2);
+        assertThat(testee.getCount(), is(equalTo(1)));
+        assertThat(testee.getUniques(), is(equalTo(2)));
+    }
+}

src/test/java/org/kohsuke/github/GHRepositoryTrafficTopReferralPathTest.java

@@ -0,0 +1,25 @@
+package org.kohsuke.github;
+
+import org.junit.Test;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.Matchers.is;
+
+/**
+ * Unit tests for {@link GHRepositoryTrafficTopReferralPath}.
+ */
+public class GHRepositoryTrafficTopReferralPathTest {
+
+    /**
+     * Test the constructor.
+     */
+    @Test
+    public void test() {
+        GHRepositoryTrafficTopReferralPath testee = new GHRepositoryTrafficTopReferralPath(1, 2, "path", "title");
+        assertThat(testee.getCount(), is(equalTo(1)));
+        assertThat(testee.getUniques(), is(equalTo(2)));
+        assertThat(testee.getPath(), is(equalTo("path")));
+        assertThat(testee.getTitle(), is(equalTo("title")));
+    }
+}

src/test/java/org/kohsuke/github/GHRepositoryTrafficTopReferralSourcesTest.java

@@ -0,0 +1,24 @@
+package org.kohsuke.github;
+
+import org.junit.Test;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.Matchers.is;
+
+/**
+ * Unit test for {@link GHRepositoryTrafficTopReferralSources}.
+ */
+public class GHRepositoryTrafficTopReferralSourcesTest {
+
+    /**
+     * Test the constructor.
+     */
+    @Test
+    public void test() {
+        GHRepositoryTrafficTopReferralSources testee = new GHRepositoryTrafficTopReferralSources(1, 2, "referrer");
+        assertThat(testee.getCount(), is(equalTo(1)));
+        assertThat(testee.getUniques(), is(equalTo(2)));
+        assertThat(testee.getReferrer(), is(equalTo("referrer")));
+    }
+}

src/test/resources/org/kohsuke/github/GHRepositoryTest/wiremock/testGetTopReferralPaths/__files/1-user.json

@@ -0,0 +1,34 @@
+{
+  "login": "ihrigb",
+  "id": 3423161,
+  "node_id": "MDQ6VXNlcjM0MjMxNjE=",
+  "avatar_url": "https://avatars.githubusercontent.com/u/3423161?v=4",
+  "gravatar_id": "",
+  "url": "https://api.github.com/users/ihrigb",
+  "html_url": "https://github.com/ihrigb",
+  "followers_url": "https://api.github.com/users/ihrigb/followers",
+  "following_url": "https://api.github.com/users/ihrigb/following{/other_user}",
+  "gists_url": "https://api.github.com/users/ihrigb/gists{/gist_id}",
+  "starred_url": "https://api.github.com/users/ihrigb/starred{/owner}{/repo}",
+  "subscriptions_url": "https://api.github.com/users/ihrigb/subscriptions",
+  "organizations_url": "https://api.github.com/users/ihrigb/orgs",
+  "repos_url": "https://api.github.com/users/ihrigb/repos",
+  "events_url": "https://api.github.com/users/ihrigb/events{/privacy}",
+  "received_events_url": "https://api.github.com/users/ihrigb/received_events",
+  "type": "User",
+  "site_admin": false,
+  "name": "Benjamin Ihrig",
+  "company": "SAP SE",
+  "blog": "",
+  "location": "Germany",
+  "email": null,
+  "hireable": null,
+  "bio": "Working at @SAP.\r\nDoing software projects for a volunteer fire brigade in free time. Smart home enthusiast. Scuba diving instructor.",
+  "twitter_username": null,
+  "public_repos": 26,
+  "public_gists": 1,
+  "followers": 5,
+  "following": 20,
+  "created_at": "2013-01-30T02:20:16Z",
+  "updated_at": "2024-02-23T21:51:51Z"
+}