Partial implementation of Organization CoPilot APIs

src/api/orgs.rs

@@ -1,5 +1,6 @@
 //! The Organization API.
 
+mod copilot;
 mod events;
 mod list_members;
 mod list_repos;
@@ -232,4 +233,14 @@ impl<'octo> OrgHandler<'octo> {
     pub fn secrets(&self) -> secrets::OrgSecretsHandler<'_> {
         secrets::OrgSecretsHandler::new(self)
     }
+
+    /// Handle copilot-related calls on the organization
+    ///
+    /// # Examples
+    /// ```no_run
+    /// let copilot_usage = octocrab::instance().orgs("org").copilot().metrics().await?;
+    /// ```
+    pub fn copilot(&self) -> copilot::CopilotHandler {
+        copilot::CopilotHandler::new(self)
+    }
 }

src/api/orgs/copilot.rs

@@ -0,0 +1,117 @@
+use super::*;
+
+#[derive(serde::Serialize)]
+pub struct CopilotHandler<'octo, 'r> {
+    #[serde(skip)]
+    handler: &'r OrgHandler<'octo>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    per_page: Option<u8>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    page: Option<u32>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    since: Option<chrono::DateTime<chrono::Utc>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    until: Option<chrono::DateTime<chrono::Utc>>,
+}
+
+impl<'octo, 'r> CopilotHandler<'octo, 'r> {
+    pub fn new(handler: &'r OrgHandler<'octo>) -> Self {
+        Self {
+            handler,
+            per_page: None,
+            page: None,
+            since: None,
+            until: None,
+        }
+    }
+
+    /// Results per page (max 100).
+    pub fn per_page(mut self, per_page: impl Into<u8>) -> Self {
+        self.per_page = Some(per_page.into());
+        self
+    }
+
+    /// Page number of the results to fetch.
+    pub fn page(mut self, page: impl Into<u32>) -> Self {
+        self.page = Some(page.into());
+        self
+    }
+
+    // Show usage metrics since this date.
+    // This is a timestamp in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
+    // Maximum value is 28 days ago.
+    pub fn since(mut self, since: chrono::DateTime<chrono::Utc>) -> Self {
+        self.since = Some(since);
+        self
+    }
+
+    // Show usage metrics until this date.
+    // This is a timestamp in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ) and should not preceed the since date if it is passed.
+    pub fn until(mut self, until: chrono::DateTime<chrono::Utc>) -> Self {
+        self.until = Some(until);
+        self
+    }
+
+    // Retrieve copilot metrics for the entire organization
+    pub async fn metrics(
+        self,
+    ) -> crate::Result<crate::Page<Vec<crate::models::orgs_copilot::metrics::CopilotMetrics>>> {
+        let route = format!("/orgs/{org}/copilot/metrics", org = self.handler.owner);
+
+        self.handler.crab.get(route, Some(&self)).await
+    }
+
+    // Retrieve copilot metrics for a specific team within the organization
+    pub async fn metrics_team<T: ToString>(
+        self,
+        team: T,
+    ) -> crate::Result<crate::Page<Vec<crate::models::orgs_copilot::metrics::CopilotMetrics>>> {
+        let route = format!(
+            "/orgs/{org}/team/{team}/copilot/metrics",
+            org = self.handler.owner,
+            team = team.to_string()
+        );
+
+        self.handler.crab.get(route, Some(&self)).await
+    }
+
+    pub async fn usage(
+        self,
+    ) -> crate::Result<crate::Page<Vec<crate::models::orgs_copilot::usage::CopilotUsage>>> {
+        let route = format!("/orgs/{org}/copilot/usage", org = self.handler.owner);
+
+        self.handler.crab.get(route, Some(&self)).await
+    }
+
+    pub async fn usage_team<T: ToString>(
+        self,
+        team: T,
+    ) -> crate::Result<crate::Page<Vec<crate::models::orgs_copilot::usage::CopilotUsage>>> {
+        let route = format!(
+            "/orgs/{org}/team/{team}/copilot/usage",
+            org = self.handler.owner,
+            team = team.to_string()
+        );
+
+        self.handler.crab.get(route, Some(&self)).await
+    }
+
+    pub async fn billing(
+        self,
+    ) -> crate::Result<crate::models::orgs_copilot::billing::CopilotBilling> {
+        let route = format!("/orgs/{org}/copilot/billing", org = self.handler.owner);
+
+        self.handler.crab.get(route, Some(&self)).await
+    }
+
+    pub async fn billing_seats(
+        self,
+    ) -> crate::Result<crate::models::orgs_copilot::billing::CopilotBillingSeats> {
+        let route = format!(
+            "/orgs/{org}/copilot/billing/seats",
+            org = self.handler.owner,
+        );
+
+        self.handler.crab.get(route, Some(&self)).await
+    }
+}

src/models.rs

@@ -22,6 +22,7 @@ pub mod gists;
 pub mod hooks;
 pub mod issues;
 pub mod orgs;
+pub mod orgs_copilot;
 pub mod pulls;
 pub mod reactions;
 pub mod repos;

src/models/orgs_copilot.rs

@@ -0,0 +1,5 @@
+use super::*;
+
+pub mod billing;
+pub mod metrics;
+pub mod usage;

src/models/orgs_copilot/billing.rs

@@ -0,0 +1,3 @@
+mod seats;
+
+pub use seats::*;

src/models/orgs_copilot/billing/seats.rs

@@ -0,0 +1,53 @@
+use super::super::*;
+
+// implements https://docs.github.com/en/rest/copilot/copilot-user-management
+// as of API Version 2022-11-28
+//
+// We have chosen to not map out the enums as the copilot API is still fresh,
+// this means GitHub may add additional enums in the future and they would
+// require more maintenance than just providing a String.
+//
+// For a list of available enums, refer to the "response schema" in the link above.
+//
+// missing:
+// - billing/seats misses the assigning_team field
+//
+// OAuth app tokens and personal access tokens (classic) need either the manage_billing:copilot, read:org, or read:enterprise scopes to use this endpoint.
+// Some of these permissions, as of writing, are only available to GitHub Enterprise customers and further limited to Enterprise Administrators.
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct CopilotBilling {
+    pub seat_breakdown: CopilotSeatBreakdown,
+    pub seat_management_setting: String,
+    pub ide_chat: String,
+    pub platform_chat: String,
+    pub cli: String,
+    pub public_code_suggestions: String,
+    pub plan_type: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct CopilotSeatBreakdown {
+    pub total: u32,
+    pub added_this_cycle: u32,
+    pub pending_invitation: u32,
+    pub pending_cancellation: u32,
+    pub active_this_cycle: u32,
+    pub inactive_this_cycle: u32,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct CopilotBillingSeats {
+    pub total_seats: u32,
+    pub seats: Vec<CopilotSeat>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct CopilotSeat {
+    pub created_at: DateTime<Utc>,
+    pub pending_cancellation_date: Option<String>,
+    pub last_activity_at: Option<DateTime<Utc>>,
+    pub last_activity_editor: Option<String>,
+    pub plan_type: Option<String>,
+    pub assignee: SimpleUser,
+}

src/models/orgs_copilot/metrics.rs

@@ -0,0 +1,61 @@
+use chrono::NaiveDate;
+
+use super::super::*;
+
+// implements https://docs.github.com/en/rest/copilot/copilot-metrics
+// as of API Version 2022-11-28
+// missing:
+// - copilot_dotcom_chat
+// - copilot_dotcom_pull_requests
+// - copilot_ide_chat
+//
+// OAuth app tokens and personal access tokens (classic) need either the manage_billing:copilot, read:org, or read:enterprise scopes to use this endpoint.
+// Some of these permissions, as of writing, are only available to GitHub Enterprise customers and further limited to Enterprise Administrators.
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct CopilotMetrics {
+    pub date: NaiveDate,
+    pub total_active_users: u32,
+    pub total_engaged_users: u32,
+    pub copilot_ide_code_completions: CopilotIdeCodeCompletions,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct CopilotIdeCodeCompletions {
+    pub total_engaged_users: u32,
+    pub languages: Vec<Language>,
+    pub editors: Vec<Editor>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct Language {
+    pub name: String,
+    pub total_engaged_users: u32,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct Editor {
+    pub name: String,
+    pub total_engaged_users: u32,
+    pub models: Vec<Model>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct Model {
+    pub name: String,
+    pub is_custom_model: bool,
+    pub custom_model_training_date: Option<NaiveDate>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub total_engaged_users: Option<u32>,
+    pub languages: Vec<EditorLanguage>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct EditorLanguage {
+    pub name: String,
+    pub total_engaged_users: u32,
+    pub total_code_suggestions: u32,
+    pub total_code_acceptances: u32,
+    pub total_code_lines_suggested: u32,
+    pub total_code_lines_accepted: u32,
+}

src/models/orgs_copilot/usage.rs

@@ -0,0 +1,34 @@
+use chrono::NaiveDate;
+
+use super::super::*;
+
+// implements https://docs.github.com/en/rest/copilot/copilot-usage
+// as of API Version 2022-11-28
+//
+// OAuth app tokens and personal access tokens (classic) need either the manage_billing:copilot, read:org, or read:enterprise scopes to use this endpoint.
+// Some of these permissions, as of writing, are only available to GitHub Enterprise customers and further limited to Enterprise Administrators.
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct CopilotUsage {
+    pub day: NaiveDate,
+    pub total_suggestions_count: u32,
+    pub total_acceptances_count: u32,
+    pub total_lines_suggested: u32,
+    pub total_lines_accepted: u32,
+    pub total_active_users: u32,
+    pub total_chat_acceptances: u32,
+    pub total_chat_turns: u32,
+    pub total_active_chat_users: u32,
+    pub breakdown: Vec<CopilotBreakdown>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct CopilotBreakdown {
+    pub language: String,
+    pub editor: String,
+    pub suggestions_count: u32,
+    pub acceptances_count: u32,
+    pub lines_suggested: u32,
+    pub lines_accepted: u32,
+    pub active_users: u32,
+}