Struct SunoClient 

pub struct SunoClient<C> { /* private fields */ }

A client for the Suno library API, owning the account’s ClerkAuth.

The Clock is held so api_request can back off through the port on a 429 or transient failure, and paged listings can pace themselves under Suno’s rate limiter — the engine still sleeps nowhere itself.

Implementations

impl<C: Clock> SunoClient<C>

pub fn new(auth: ClerkAuth, clock: C) -> Self

Create a client from a fresh or already-authenticated ClerkAuth.

pub fn auth(&self) -> &ClerkAuth

Borrow the underlying authenticator.

pub async fn list_clips( &mut self, http: &impl Http, liked: bool, limit: Option<usize>, ) -> Result<(Vec<Clip>, bool)>

List clips across the whole library, or only liked clips.

Stops early once limit clips are collected. Paging is hard-capped at [MAX_PAGES] so a runaway has_more can never loop forever.

Returns the clips paired with a complete flag that is true only when paging ended because the server reported has_more == false (the feed fully drained). A limit stop, or exhausting [MAX_PAGES] while has_more is still set, yields false so the caller can refuse to treat a truncated listing as authoritative for deletion.

pub async fn get_clip(&mut self, http: &impl Http, id: &str) -> Result<Clip>

Fetch one clip by ID.

Tries the dedicated /api/clip/{id} endpoint first, then falls back to scanning the library feed, since that endpoint’s exact shape is not yet confirmed against the live API.

pub async fn request_wav(&mut self, http: &impl Http, id: &str) -> Result<()>

Ask Suno to render a clip to lossless WAV (server-side, asynchronous).

pub async fn wav_url( &mut self, http: &impl Http, id: &str, ) -> Result<Option<String>>

Read the rendered WAV URL for a clip, or None while it is not ready.

pub async fn get_clips_by_ids( &mut self, http: &impl Http, ids: &[&str], ) -> Result<Vec<Clip>>

Fetch specific clips by id through the feed’s ?ids= filter.

Used by lineage resolution to gap-fill ancestors that are absent from a normal listing, including trashed ones. Unlike list_clips, no keep_clip filtering is applied: an ancestor may itself be an infill or context-window artefact that the lineage walk must still traverse. Clips returned here are ancestors for resolution only and must never be treated as download candidates. Ids are chunked so a long list cannot build an over-long URL.

pub async fn get_clip_parent( &mut self, http: &impl Http, id: &str, ) -> Result<Option<Clip>>

Fetch a clip’s immediate parent via the dedicated parent endpoint.

Returns the parent clip, or None when the clip is a root (no parent) or the endpoint yields no clip. Lineage resolution uses this as a fallback when a missing ancestor cannot be retrieved by id. Only a 404 (the clip has no parent) maps to None; any other failure, including a transient 5xx, propagates as an error rather than being mistaken for a root.

pub async fn get_playlists(&mut self, http: &impl Http) -> Result<Vec<Playlist>>

List the account’s own playlists, paging /api/playlist/me.

Trashed and share-list playlists are excluded by query, so the result is the account’s authoritative own set. Paging stops on the first empty page and is hard-capped at [MAX_PAGES] so a server that ignores the page parameter cannot loop forever. Only entries with a non-empty id are kept.

A hard failure propagates as an error; the caller treats that as “the playlist listing did not fully enumerate” and refuses every playlist deletion this run, so a dropped fetch can never remove a .m3u8.

pub async fn get_playlist_clips( &mut self, http: &impl Http, id: &str, ) -> Result<Vec<Clip>>

Fetch one playlist’s clips in Suno order via /api/playlist/{id}/.

The response’s playlist_clips[] is already ordered and trashed members are excluded by Suno, so the order is preserved exactly and no keep_clip filtering is applied — a playlist may legitimately contain any clip. Each entry’s clip object is mapped (falling back to the entry itself), and only clips with a non-empty id are kept.