From 9e237e766d99ba80f4a2e1e9c9a8039c7400af82 Mon Sep 17 00:00:00 2001
From: Vaibhav Yenamandra <3663231+envp@users.noreply.github.com>
Date: Mon, 17 Apr 2023 02:40:35 -0400
Subject: [PATCH] gists: Handle fork related operations (#339)

* gists: Handle `GET gists/{gist_id}/forks`

Fetches a sequence of gists that have forked the given `gist_id`.

* gists: Handle `POST /gists/{gist_id}/forks`

Calling this endpoint forks the gist_id to the authenticated user's
account.
---
 src/api/gists.rs            | 31 +++++++++++++++++++++++
 src/api/gists/list_forks.rs | 50 +++++++++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+)
 create mode 100644 src/api/gists/list_forks.rs

diff --git a/src/api/gists.rs b/src/api/gists.rs
index 785554f9..dbdcf6c8 100644
--- a/src/api/gists.rs
+++ b/src/api/gists.rs
@@ -1,5 +1,6 @@
 //! The gist API
 mod list_commits;
+mod list_forks;
 
 use http::StatusCode;
 use serde::Serialize;
@@ -209,6 +210,36 @@ impl<'octo> GistsHandler<'octo> {
             .await
             .map(|_| ())
     }
+
+    /// Retrieve all the gists that forked the given `gist_id`. See
+    /// [GitHub API Docs][docs] for information about request parameters, and
+    /// response schema.
+    ///
+    /// ```no_run
+    /// # async fn run() -> octocrab::Result<()> {
+    /// octocrab::instance()
+    ///     .gists()
+    ///     .list_forks("00000000000000000000000000000000")
+    ///     .send()
+    ///     .await?;
+    /// # Ok(())
+    /// # }
+    /// ```
+    ///
+    /// [docs]: https://docs.github.com/en/rest/gists/gists?apiVersion=2022-11-28#list-gist-forks
+    pub fn list_forks(&self, gist_id: impl Into<String>) -> list_forks::ListGistForksBuilder {
+        list_forks::ListGistForksBuilder::new(self, gist_id.into())
+    }
+
+    /// Create a fork of the given `gist_id` associated with the authenticated
+    /// user's account. See [GitHub API docs][docs] for more information about
+    /// request parameters and response schema.
+    ///
+    /// [docs]: https://docs.github.com/en/rest/gists/gists?apiVersion=2022-11-28#fork-a-gist
+    pub async fn fork(&self, gist_id: impl AsRef<str>) -> Result<Gist> {
+        let route = format!("/gists/{gist_id}/forks", gist_id = gist_id.as_ref());
+        self.crab.post(route, None::<&()>).await
+    }
 }
 
 #[derive(Debug)]
diff --git a/src/api/gists/list_forks.rs b/src/api/gists/list_forks.rs
new file mode 100644
index 00000000..ef36ae13
--- /dev/null
+++ b/src/api/gists/list_forks.rs
@@ -0,0 +1,50 @@
+use crate::{gists::GistsHandler, models::gists::Gist, Page, Result};
+use serde;
+
+#[derive(serde::Serialize)]
+pub struct ListGistForksBuilder<'octo, 'b> {
+    #[serde(skip)]
+    handler: &'b GistsHandler<'octo>,
+    #[serde(skip)]
+    gist_id: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    per_page: Option<u8>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    page: Option<u32>,
+}
+
+impl<'octo, 'b> ListGistForksBuilder<'octo, 'b> {
+    pub(crate) fn new(handler: &'b GistsHandler<'octo>, gist_id: String) -> Self {
+        Self {
+            handler,
+            gist_id,
+            per_page: None,
+            page: None,
+        }
+    }
+
+    /// Set the `per_page` query parameter on the builder.
+    ///
+    /// Controls the number of results to return per "page" of results.
+    /// The maximum value is 100 results per page retrieved. Values larger than
+    /// `100` are clamped to `100` by GitHub's API
+    pub fn per_page(mut self, count: u8) -> Self {
+        self.per_page = Some(count);
+        self
+    }
+
+    /// Sets the `page` query parameter on the builder.
+    ///
+    /// Controls which page of the result set should be retrieved.
+    /// All pages are retrieved if this is omitted.
+    pub fn page(mut self, page_num: u32) -> Self {
+        self.page = Some(page_num);
+        self
+    }
+
+    /// Sends the actual request to GitHub's API
+    pub async fn send(self) -> Result<Page<Gist>> {
+        let route = format!("/gists/{gist_id}/forks", gist_id = self.gist_id);
+        self.handler.crab.get(route, Some(&self)).await
+    }
+}