feat(0.10.0): Phases 9 + 10 — Models listing and self-hosted credentials

  Phase 9: GET /v1/models, /v1/models/{id}, and project variants.
  ModelInfo flattens the spec's oneOf [STT, TTS] into one struct with
  optional feature fields. Wired as Deepgram::models() under the
  existing `manage` feature.

  Phase 10: list/create/get/delete on
  /v1/projects/{id}/self-hosted/distribution/credentials. Scope is an
  8-variant enum, Provider is a 1-variant enum (Quay). New
  `self_hosted` feature flag, off by default — the audience is
  self-hosted operators only.

  Both phases are purely additive — no breaking changes.

Author: GregHolmes

Cargo.toml

@@ -61,6 +61,7 @@ listen = ["dep:tungstenite", "dep:tokio-tungstenite"]
 speak = ["dep:tungstenite", "dep:tokio-tungstenite"]
 agent = ["dep:tungstenite", "dep:tokio-tungstenite"]
 read = []
+self_hosted = []
 
 [[example]]
 name = "grant_token"
@@ -195,3 +196,13 @@ required-features = ["agent"]
 name = "agent_variables"
 path = "examples/agent/rest/variables.rs"
 required-features = ["agent"]
+
+[[example]]
+name = "manage_models"
+path = "examples/manage/models.rs"
+required-features = ["manage"]
+
+[[example]]
+name = "self_hosted_distribution_credentials"
+path = "examples/self_hosted/distribution_credentials.rs"
+required-features = ["self_hosted"]

examples/manage/models.rs

@@ -0,0 +1,37 @@
+use deepgram::{manage::models::list_options, Deepgram, DeepgramError};
+use std::env;
+
+#[tokio::main]
+async fn main() -> Result<(), DeepgramError> {
+    let deepgram_api_key =
+        env::var("DEEPGRAM_API_KEY").expect("DEEPGRAM_API_KEY environmental variable");
+
+    let project_id =
+        env::var("DEEPGRAM_PROJECT_ID").expect("DEEPGRAM_PROJECT_ID environmental variable");
+
+    let dg_client = Deepgram::new(&deepgram_api_key)?;
+
+    let opts = list_options::Options::builder()
+        .include_outdated(false)
+        .build();
+
+    let public = dg_client.models().list(&opts).await?;
+    println!("public: {} STT, {} TTS", public.stt.len(), public.tts.len());
+
+    let project = dg_client
+        .models()
+        .list_for_project(&project_id, &opts)
+        .await?;
+    println!(
+        "project: {} STT, {} TTS",
+        project.stt.len(),
+        project.tts.len()
+    );
+
+    if let Some(first) = public.stt.first() {
+        let detail = dg_client.models().get(&first.uuid).await?;
+        println!("{}: {}", detail.canonical_name, detail.version);
+    }
+
+    Ok(())
+}

examples/self_hosted/distribution_credentials.rs

@@ -0,0 +1,54 @@
+use deepgram::{
+    self_hosted::distribution_credentials::create_options::{Options, Provider, Scope},
+    Deepgram, DeepgramError,
+};
+use std::env;
+
+#[tokio::main]
+async fn main() -> Result<(), DeepgramError> {
+    let deepgram_api_key =
+        env::var("DEEPGRAM_API_KEY").expect("DEEPGRAM_API_KEY environmental variable");
+
+    let project_id =
+        env::var("DEEPGRAM_PROJECT_ID").expect("DEEPGRAM_PROJECT_ID environmental variable");
+
+    let dg_client = Deepgram::new(&deepgram_api_key)?;
+
+    let existing = dg_client
+        .distribution_credentials()
+        .list(&project_id)
+        .await?;
+    println!(
+        "existing credential sets: {}",
+        existing.distribution_credentials.len()
+    );
+
+    let opts = Options::builder()
+        .scopes([Scope::ProductApi, Scope::ProductEngine])
+        .provider(Provider::Quay)
+        .comment("created by deepgram-rust-sdk example")
+        .build();
+    let created = dg_client
+        .distribution_credentials()
+        .create(&project_id, &opts)
+        .await?;
+    let credentials_id = created.distribution_credentials.distribution_credentials_id;
+    println!("created: {credentials_id}");
+
+    let fetched = dg_client
+        .distribution_credentials()
+        .get(&project_id, &credentials_id)
+        .await?;
+    println!(
+        "scopes on fetched: {:?}",
+        fetched.distribution_credentials.scopes
+    );
+
+    dg_client
+        .distribution_credentials()
+        .delete(&project_id, &credentials_id)
+        .await?;
+    println!("deleted: {credentials_id}");
+
+    Ok(())
+}

src/lib.rs

@@ -35,6 +35,8 @@ pub mod listen;
 pub mod manage;
 #[cfg(feature = "read")]
 pub mod read;
+#[cfg(feature = "self_hosted")]
+pub mod self_hosted;
 #[cfg(feature = "speak")]
 pub mod speak;
 

src/manage/mod.rs

@@ -4,6 +4,7 @@ pub mod billing;
 pub mod invitations;
 pub mod keys;
 pub mod members;
+pub mod models;
 pub mod projects;
 pub mod scopes;
 pub mod usage;

src/manage/models.rs

@@ -0,0 +1,80 @@
+//! List and look up Deepgram models, both public and project-scoped.
+//!
+//! See the [Deepgram API Reference][api] for more info.
+//!
+//! [api]: https://developers.deepgram.com/reference/manage-api/get-models
+
+use crate::{
+    manage::models::response::{ListModelsResponse, ModelInfo},
+    send_and_translate_response, Deepgram,
+};
+
+pub mod list_options;
+pub mod response;
+
+/// Sub-client for the model-listing endpoints. Constructed via
+/// [`Deepgram::models`].
+#[derive(Debug, Clone)]
+pub struct Models<'a>(&'a Deepgram);
+
+impl Deepgram {
+    /// Construct a new [`Models`] sub-client.
+    pub fn models(&self) -> Models<'_> {
+        self.into()
+    }
+}
+
+impl<'a> From<&'a Deepgram> for Models<'a> {
+    fn from(deepgram: &'a Deepgram) -> Self {
+        Self(deepgram)
+    }
+}
+
+impl Models<'_> {
+    /// `GET /v1/models` — metadata for all latest public models.
+    ///
+    /// To list project-scoped (including non-public) models, use
+    /// [`Models::list_for_project`].
+    pub async fn list(&self, options: &list_options::Options) -> crate::Result<ListModelsResponse> {
+        let url = "https://api.deepgram.com/v1/models";
+        let mut request = self.0.client.get(url);
+        let pairs = options.query_pairs();
+        if !pairs.is_empty() {
+            request = request.query(&pairs);
+        }
+        send_and_translate_response(request).await
+    }
+
+    /// `GET /v1/models/{model_id}` — metadata for one public model.
+    pub async fn get(&self, model_id: &str) -> crate::Result<ModelInfo> {
+        let url = format!("https://api.deepgram.com/v1/models/{model_id}");
+        send_and_translate_response(self.0.client.get(url)).await
+    }
+
+    /// `GET /v1/projects/{project_id}/models` — metadata for all
+    /// models the project has access to, including non-public ones.
+    pub async fn list_for_project(
+        &self,
+        project_id: &str,
+        options: &list_options::Options,
+    ) -> crate::Result<ListModelsResponse> {
+        let url = format!("https://api.deepgram.com/v1/projects/{project_id}/models");
+        let mut request = self.0.client.get(url);
+        let pairs = options.query_pairs();
+        if !pairs.is_empty() {
+            request = request.query(&pairs);
+        }
+        send_and_translate_response(request).await
+    }
+
+    /// `GET /v1/projects/{project_id}/models/{model_id}` — metadata
+    /// for a single project-scoped model.
+    pub async fn get_for_project(
+        &self,
+        project_id: &str,
+        model_id: &str,
+    ) -> crate::Result<ModelInfo> {
+        let url = format!("https://api.deepgram.com/v1/projects/{project_id}/models/{model_id}");
+        send_and_translate_response(self.0.client.get(url)).await
+    }
+}

src/manage/models/list_options.rs

@@ -0,0 +1,51 @@
+//! Options for the model-listing endpoints.
+//!
+//! Mirrors the `include_outdated` query param shared by
+//! `GET /v1/models` and `GET /v1/projects/{id}/models`.
+
+/// Options for [`Models::list`](super::super::Models::list) and
+/// [`Models::list_for_project`](super::super::Models::list_for_project).
+#[derive(Debug, Default, PartialEq, Clone, Copy)]
+pub struct Options {
+    include_outdated: Option<bool>,
+}
+
+/// Builder for [`Options`].
+#[derive(Debug, Default, PartialEq, Clone, Copy)]
+pub struct OptionsBuilder(Options);
+
+impl Options {
+    /// Construct a new [`OptionsBuilder`].
+    pub fn builder() -> OptionsBuilder {
+        OptionsBuilder::default()
+    }
+
+    pub(super) fn query_pairs(&self) -> Vec<(&'static str, &'static str)> {
+        let mut pairs = Vec::new();
+        if let Some(include_outdated) = self.include_outdated {
+            pairs.push((
+                "include_outdated",
+                if include_outdated { "true" } else { "false" },
+            ));
+        }
+        pairs
+    }
+}
+
+impl OptionsBuilder {
+    /// Construct a fresh empty builder.
+    pub fn new() -> Self {
+        Self(Options::default())
+    }
+
+    /// When `true`, include non-latest model versions in the response.
+    pub fn include_outdated(mut self, include_outdated: bool) -> Self {
+        self.0.include_outdated = Some(include_outdated);
+        self
+    }
+
+    /// Finish building.
+    pub fn build(self) -> Options {
+        self.0
+    }
+}