feat(manage): close the Phase 6 gaps

  Phase 6 of the spec-coverage rollout — five sub-tasks across Manage.

  6a. Usage::get_usage_breakdown for /v1/projects/{id}/usage/breakdown
      (with UsageGrouping enum and richer response shape — agent
      hours, token counts, TTS characters, per-row grouping). Existing
      Usage::get_usage marked #[deprecated(since = "0.10.0")] —
      /v1/projects/{id}/usage is deprecated server-side.

  6b. Invitations CRUD: Invitations::{list, create, delete} alongside
      the existing leave_project. options::Options{email, scope} +
      response::{Invites, Invite}.

  6c. Billing::{breakdown, fields, purchases} with a new
      breakdown_options module (BillingGrouping enum, 4 values).
      Custom-Serialize options to emit repeated grouping=… params
      correctly through serde_urlencoded. New response types:
      BillingBreakdown(Result|Grouping), BillingFields, PurchaseOrders,
      PurchaseOrder, Resolution.

  6d. list_requests_options gains page, accessor, request_id,
      deployment (DeploymentFilter), endpoint (EndpointFilter), and
      method (HttpMethodFilter — name-disambiguated from the existing
      get_usage_options::Method which means a different thing).

  6e. Breaking signature changes for 0.10.0:
      - Keys::list(project_id, status: Option<KeyStatus>)
      - Projects::get(project_id, limit: Option<u32>, page: Option<u32>)

  223 lib tests pass (+12), 7 integration tests pass, 139 doctests
  pass. All feature combinations build clean.

Author: GregHolmes

src/manage/billing.rs

@@ -5,10 +5,13 @@
 //! [api]: https://developers.deepgram.com/api-reference/#billing
 
 use crate::{
-    manage::billing::response::{Balance, Balances},
+    manage::billing::response::{
+        Balance, Balances, BillingBreakdown, BillingFields, PurchaseOrders,
+    },
     send_and_translate_response, Deepgram,
 };
 
+pub mod breakdown_options;
 pub mod response;
 
 /// Get the outstanding balances for a Deepgram Project.
@@ -113,6 +116,63 @@ impl Billing<'_> {
 
         send_and_translate_response(self.0.client.get(url)).await
     }
+
+    /// `GET /v1/projects/{project_id}/billing/breakdown` — billing
+    /// summary for the project, with optional filters and grouping.
+    pub async fn breakdown(
+        &self,
+        project_id: &str,
+        options: &breakdown_options::Options,
+    ) -> crate::Result<BillingBreakdown> {
+        let url = format!("https://api.deepgram.com/v1/projects/{project_id}/billing/breakdown");
+        let request = self
+            .0
+            .client
+            .get(url)
+            .query(&breakdown_options::SerializableOptions(options));
+        send_and_translate_response(request).await
+    }
+
+    /// `GET /v1/projects/{project_id}/billing/fields` — list the
+    /// dimensions (accessors, deployments, tags, line items) available
+    /// for filtering [`Billing::breakdown`] queries over the given
+    /// date range.
+    pub async fn fields(
+        &self,
+        project_id: &str,
+        start: Option<&str>,
+        end: Option<&str>,
+    ) -> crate::Result<BillingFields> {
+        let url = format!("https://api.deepgram.com/v1/projects/{project_id}/billing/fields");
+        let mut request = self.0.client.get(url);
+        let mut query: Vec<(&str, &str)> = Vec::new();
+        if let Some(start) = start {
+            query.push(("start", start));
+        }
+        if let Some(end) = end {
+            query.push(("end", end));
+        }
+        if !query.is_empty() {
+            request = request.query(&query);
+        }
+        send_and_translate_response(request).await
+    }
+
+    /// `GET /v1/projects/{project_id}/purchases` — list purchase
+    /// orders for the project. `limit` is forwarded as the
+    /// per-page-size query param (1-1000 per spec).
+    pub async fn purchases(
+        &self,
+        project_id: &str,
+        limit: Option<usize>,
+    ) -> crate::Result<PurchaseOrders> {
+        let url = format!("https://api.deepgram.com/v1/projects/{project_id}/purchases");
+        let mut request = self.0.client.get(url);
+        if let Some(limit) = limit {
+            request = request.query(&[("limit", limit)]);
+        }
+        send_and_translate_response(request).await
+    }
 }
 
 #[cfg(test)]

src/manage/billing/breakdown_options.rs

@@ -0,0 +1,190 @@
+//! Options for [`Billing::breakdown`](super::Billing::breakdown).
+//!
+//! Mirrors the query params on `GET /v1/projects/{id}/billing/breakdown`.
+
+use serde::ser::SerializeSeq;
+use serde::{Serialize, Serializer};
+
+/// Options for the billing breakdown endpoint.
+#[derive(Debug, Default, PartialEq, Clone)]
+pub struct Options {
+    start: Option<String>,
+    end: Option<String>,
+    accessor: Option<String>,
+    deployment: Option<String>,
+    tag: Option<String>,
+    line_item: Option<String>,
+    grouping: Vec<BillingGrouping>,
+}
+
+/// `?grouping=` value for `billing/breakdown`. Distinct from
+/// [`crate::manage::usage::get_usage_breakdown_options::UsageGrouping`]
+/// — billing supports a strict 4-value subset.
+#[derive(Debug, PartialEq, Eq, Clone, Copy, Hash)]
+#[non_exhaustive]
+pub enum BillingGrouping {
+    /// Group by accessor (e.g. API key UUID).
+    Accessor,
+    /// Group by deployment type.
+    Deployment,
+    /// Group by line item (e.g. `streaming::nova-3`).
+    LineItem,
+    /// Group by tag.
+    Tags,
+}
+
+impl BillingGrouping {
+    fn as_str(&self) -> &'static str {
+        match self {
+            Self::Accessor => "accessor",
+            Self::Deployment => "deployment",
+            Self::LineItem => "line_item",
+            Self::Tags => "tags",
+        }
+    }
+}
+
+/// Builder for [`Options`].
+#[derive(Debug, Default, PartialEq, Clone)]
+pub struct OptionsBuilder(Options);
+
+/// Wire serializer for [`Options`]. Emits a flat sequence of
+/// `(key, value)` tuples so that repeated `grouping=…` params work
+/// (`serde_urlencoded` doesn't support sequence-typed fields inside a
+/// struct, only at the top level).
+#[doc(hidden)]
+#[derive(Debug)]
+pub struct SerializableOptions<'a>(pub(crate) &'a Options);
+
+impl Serialize for SerializableOptions<'_> {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        let opts = self.0;
+        let mut seq = serializer.serialize_seq(None)?;
+
+        if let Some(start) = &opts.start {
+            seq.serialize_element(&("start", start))?;
+        }
+        if let Some(end) = &opts.end {
+            seq.serialize_element(&("end", end))?;
+        }
+        if let Some(accessor) = &opts.accessor {
+            seq.serialize_element(&("accessor", accessor))?;
+        }
+        if let Some(deployment) = &opts.deployment {
+            seq.serialize_element(&("deployment", deployment))?;
+        }
+        if let Some(tag) = &opts.tag {
+            seq.serialize_element(&("tag", tag))?;
+        }
+        if let Some(line_item) = &opts.line_item {
+            seq.serialize_element(&("line_item", line_item))?;
+        }
+        for g in &opts.grouping {
+            seq.serialize_element(&("grouping", g.as_str()))?;
+        }
+
+        seq.end()
+    }
+}
+
+impl Options {
+    /// Construct a new builder.
+    pub fn builder() -> OptionsBuilder {
+        OptionsBuilder::default()
+    }
+
+    /// URL-encoded query string (without leading `?`).
+    pub fn urlencoded(&self) -> Result<String, serde_urlencoded::ser::Error> {
+        serde_urlencoded::to_string(SerializableOptions(self))
+    }
+}
+
+impl OptionsBuilder {
+    /// Construct a fresh empty builder.
+    pub fn new() -> Self {
+        Self(Options::default())
+    }
+
+    /// Start of the requested date range. `YYYY-MM-DD` format.
+    pub fn start(mut self, start: impl Into<String>) -> Self {
+        self.0.start = Some(start.into());
+        self
+    }
+
+    /// End of the requested date range. `YYYY-MM-DD` format.
+    pub fn end(mut self, end: impl Into<String>) -> Self {
+        self.0.end = Some(end.into());
+        self
+    }
+
+    /// Filter by accessor (UUID).
+    pub fn accessor(mut self, accessor: impl Into<String>) -> Self {
+        self.0.accessor = Some(accessor.into());
+        self
+    }
+
+    /// Filter by deployment type.
+    pub fn deployment(mut self, deployment: impl Into<String>) -> Self {
+        self.0.deployment = Some(deployment.into());
+        self
+    }
+
+    /// Filter by tag.
+    pub fn tag(mut self, tag: impl Into<String>) -> Self {
+        self.0.tag = Some(tag.into());
+        self
+    }
+
+    /// Filter by line item (e.g. `streaming::nova-3`).
+    pub fn line_item(mut self, line_item: impl Into<String>) -> Self {
+        self.0.line_item = Some(line_item.into());
+        self
+    }
+
+    /// Replace the grouping list. Multiple groupings are sent as
+    /// repeated query params.
+    pub fn grouping<I>(mut self, grouping: I) -> Self
+    where
+        I: IntoIterator<Item = BillingGrouping>,
+    {
+        self.0.grouping = grouping.into_iter().collect();
+        self
+    }
+
+    /// Finish building.
+    pub fn build(self) -> Options {
+        self.0
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn empty_options() {
+        let q = Options::builder().build().urlencoded().unwrap();
+        assert_eq!(q, "");
+    }
+
+    #[test]
+    fn full_options_serialize() {
+        let q = Options::builder()
+            .start("2025-01-01")
+            .end("2025-01-31")
+            .accessor("acc-1")
+            .deployment("hosted")
+            .tag("prod")
+            .line_item("streaming::nova-3")
+            .grouping([BillingGrouping::Deployment, BillingGrouping::LineItem])
+            .build()
+            .urlencoded()
+            .unwrap();
+        assert_eq!(
+            q,
+            "start=2025-01-01&end=2025-01-31&accessor=acc-1\
+             &deployment=hosted&tag=prod&line_item=streaming%3A%3Anova-3\
+             &grouping=deployment&grouping=line_item"
+        );
+    }
+}

src/manage/billing/response.rs

@@ -1,5 +1,7 @@
 //! Deepgram billing API response types.
 
+use std::collections::HashMap;
+
 use serde::{Deserialize, Serialize};
 use uuid::Uuid;
 
@@ -53,3 +55,116 @@ pub enum BillingUnits {
     #[serde(rename = "hour")]
     Hour,
 }
+
+/// Returned by [`Billing::breakdown`](super::Billing::breakdown).
+#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
+#[non_exhaustive]
+pub struct BillingBreakdown {
+    /// Start of the billing period.
+    pub start: String,
+    /// End of the billing period.
+    pub end: String,
+    /// Resolution of each row in `results`.
+    pub resolution: Resolution,
+    /// One row per grouping bucket.
+    pub results: Vec<BillingBreakdownResult>,
+}
+
+/// Time resolution shared by [`BillingBreakdown`] and `UsageBreakdown`.
+#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
+#[non_exhaustive]
+pub struct Resolution {
+    /// Time unit for the resolution (e.g. `day`).
+    pub units: String,
+    /// Amount of units (e.g. `1`).
+    pub amount: f64,
+}
+
+/// One row of a [`BillingBreakdown`].
+#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
+#[non_exhaustive]
+pub struct BillingBreakdownResult {
+    /// USD cost for this grouping bucket.
+    pub dollars: f64,
+    /// Grouping dimensions that produced this row.
+    pub grouping: BillingBreakdownGrouping,
+}
+
+/// Grouping metadata on a [`BillingBreakdownResult`].
+#[derive(Debug, PartialEq, Clone, Default, Serialize, Deserialize)]
+#[non_exhaustive]
+pub struct BillingBreakdownGrouping {
+    #[allow(missing_docs)]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub start: Option<String>,
+
+    #[allow(missing_docs)]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub end: Option<String>,
+
+    #[allow(missing_docs)]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub accessor: Option<String>,
+
+    #[allow(missing_docs)]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub deployment: Option<String>,
+
+    #[allow(missing_docs)]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub line_item: Option<String>,
+
+    #[allow(missing_docs)]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tags: Option<Vec<String>>,
+}
+
+/// Returned by [`Billing::fields`](super::Billing::fields). Lists the
+/// dimensions available for filtering [`BillingBreakdown`] queries.
+#[derive(Debug, PartialEq, Eq, Clone, Default, Serialize, Deserialize)]
+#[non_exhaustive]
+pub struct BillingFields {
+    /// Accessor UUIDs that have produced billing in the time range.
+    #[serde(default)]
+    pub accessors: Vec<String>,
+
+    /// Deployment types that have produced billing.
+    #[serde(default)]
+    pub deployments: Vec<String>,
+
+    /// Tags that have produced billing.
+    #[serde(default)]
+    pub tags: Vec<String>,
+
+    /// Line item identifiers mapped to human-readable descriptions.
+    /// e.g. `"streaming::nova-3" -> "Nova-3 (Stream)"`.
+    #[serde(default)]
+    pub line_items: HashMap<String, String>,
+}
+
+/// Returned by [`Billing::purchases`](super::Billing::purchases).
+#[derive(Debug, PartialEq, Clone, Default, Serialize, Deserialize)]
+#[non_exhaustive]
+pub struct PurchaseOrders {
+    /// Purchase orders.
+    #[serde(default)]
+    pub orders: Vec<PurchaseOrder>,
+}
+
+/// A single purchase order.
+#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
+#[non_exhaustive]
+pub struct PurchaseOrder {
+    /// Order UUID.
+    pub order_id: Uuid,
+    /// Expiration timestamp (ISO 8601).
+    pub expiration: String,
+    /// Creation timestamp (ISO 8601).
+    pub created: String,
+    /// Amount of the purchase.
+    pub amount: f64,
+    /// Units of the amount (e.g. `usd`).
+    pub units: String,
+    /// Type of order (e.g. `promotional`).
+    pub order_type: String,
+}