Struct Client 

pub struct Client { /* private fields */ }

Threads API client. Thread-safe; wrap in Arc<Client> to share across tasks.

Implementations

impl Client

pub async fn get_post_insights( &self, post_id: &PostId, metrics: &[&str], ) -> Result<InsightsResponse>

Get insights for a specific post.

pub async fn get_account_insights( &self, user_id: &UserId, metrics: &[&str], period: &str, ) -> Result<InsightsResponse>

Get insights for a user account.

pub async fn get_post_insights_with_options( &self, post_id: &PostId, opts: &PostInsightsOptions, ) -> Result<InsightsResponse>

Get post insights with typed options.

pub async fn get_account_insights_with_options( &self, user_id: &UserId, opts: &AccountInsightsOptions, ) -> Result<InsightsResponse>

Get account insights with typed options.

impl Client

pub async fn search_locations( &self, query: Option<&str>, latitude: Option<f64>, longitude: Option<f64>, ) -> Result<LocationSearchResponse>

Search for locations by query string, coordinates, or both.

Per the API docs, you can search by query alone, latitude + longitude alone, or all three together. At least one of query or coordinates must be provided.

pub async fn get_location(&self, location_id: &LocationId) -> Result<Location>

Get a location by ID.

impl Client

pub async fn create_text_post(&self, content: &TextPostContent) -> Result<Post>

Create a text post. If auto_publish_text is true, skips the container+publish flow and posts directly.

pub async fn create_image_post( &self, content: &ImagePostContent, ) -> Result<Post>

Create an image post.

pub async fn create_video_post( &self, content: &VideoPostContent, ) -> Result<Post>

Create a video post.

pub async fn create_carousel_post( &self, content: &CarouselPostContent, ) -> Result<Post>

Create a carousel post.

pub async fn create_quote_post( &self, text: &str, quoted_post_id: &PostId, ) -> Result<Post>

Create a quote post — a text post that quotes another post.

pub async fn create_media_container( &self, media_type: &str, media_url: &str, alt_text: Option<&str>, ) -> Result<ContainerId>

Create a media container and return its ID.

Public wrapper around the internal container creation. Useful for building carousel children or custom publishing flows.

Note: The container is returned immediately after creation. The caller must poll get_container_status until the status is FINISHED before using the container in a publish call (e.g. create_carousel_post).

pub async fn repost_post(&self, post_id: &PostId) -> Result<PostId>

Repost an existing post and return the repost’s post ID.

Unlike the previous implementation, this does not make an extra API call to fetch the full post. Call get_post on the returned ID if you need the full post details.

pub async fn get_container_status( &self, container_id: &ContainerId, ) -> Result<ContainerStatus>

Get the status of a media container.

impl Client

pub async fn delete_post(&self, post_id: &PostId) -> Result<String>

Delete a post by ID. Returns the deleted post ID.

impl Client

pub async fn get_post(&self, post_id: &PostId) -> Result<Post>

Get a single post by ID with extended fields.

pub async fn get_user_posts( &self, user_id: &UserId, opts: Option<&PostsOptions>, ) -> Result<PostsResponse>

Get posts created by a user.

pub async fn get_user_mentions( &self, user_id: &UserId, opts: Option<&PostsOptions>, ) -> Result<PostsResponse>

Get posts where the user is mentioned.

Supports since and until for time-range filtering in addition to cursor-based pagination.

pub async fn get_user_ghost_posts( &self, user_id: &UserId, opts: Option<&PostsOptions>, ) -> Result<PostsResponse>

Get ghost posts for a user.

Supports since and until for time-range filtering in addition to cursor-based pagination.

pub async fn get_publishing_limits(&self) -> Result<PublishingLimits>

Get the publishing rate limits for the authenticated user.

impl Client

pub async fn get_replies( &self, post_id: &PostId, opts: Option<&RepliesOptions>, ) -> Result<RepliesResponse>

Get replies to a post.

pub async fn get_conversation( &self, post_id: &PostId, opts: Option<&RepliesOptions>, ) -> Result<RepliesResponse>

Get the full conversation thread for a post.

pub async fn get_pending_replies( &self, post_id: &PostId, opts: Option<&PendingRepliesOptions>, ) -> Result<RepliesResponse>

Get pending replies awaiting moderation.

pub async fn approve_pending_reply(&self, reply_id: &PostId) -> Result<()>

Approve a pending reply.

pub async fn ignore_pending_reply(&self, reply_id: &PostId) -> Result<()>

Ignore a pending reply.

pub async fn hide_reply(&self, reply_id: &PostId) -> Result<()>

Hide a reply.

pub async fn reply_to_post(&self, post_id: &PostId, text: &str) -> Result<Post>

Reply to a post with text.

Convenience wrapper: builds a TextPostContent with reply_to_id set and delegates to create_text_post.

pub async fn create_reply( &self, content: &TextPostContent, apply_reply_delay: bool, ) -> Result<Post>

Create a text reply.

Validates that reply_to_id is set, then delegates to create_text_post. Set apply_reply_delay to true to apply the API-recommended 10-second delay before creating the reply.

pub async fn create_image_reply( &self, content: &ImagePostContent, ) -> Result<Post>

Create an image reply.

Validates that reply_to_id is set, then delegates to create_image_post.

pub async fn create_video_reply( &self, content: &VideoPostContent, ) -> Result<Post>

Create a video reply.

Validates that reply_to_id is set, then delegates to create_video_post.

pub async fn unhide_reply(&self, reply_id: &PostId) -> Result<()>

Unhide a reply.

impl Client

pub async fn keyword_search( &self, query: &str, opts: Option<&SearchOptions>, ) -> Result<PostsResponse>

Search for posts by keyword.

pub async fn hashtag_search( &self, tag: &str, opts: Option<&SearchOptions>, ) -> Result<PostsResponse>

Search for posts by hashtag.

Convenience wrapper around keyword_search with search_mode set to TAG.

impl Client

pub async fn get_user(&self, user_id: &UserId) -> Result<User>

Get a user profile by ID.

pub async fn get_me(&self) -> Result<User>

Get the authenticated user’s profile.

pub async fn lookup_public_profile(&self, username: &str) -> Result<PublicUser>

Look up a public user profile by username.

pub async fn get_user_with_fields( &self, user_id: &UserId, fields: &[&str], ) -> Result<User>

Get a user profile with custom field selection.

pub async fn get_public_profile_posts( &self, username: &str, opts: Option<&PostsOptions>, ) -> Result<PostsResponse>

Get posts from a public user profile by username.

pub async fn get_user_replies( &self, user_id: &UserId, opts: Option<&PostsOptions>, ) -> Result<RepliesResponse>

Get replies posted by a user.

pub async fn get_my_posts( &self, opts: Option<&PostsOptions>, ) -> Result<PostsResponse>

Get the authenticated user’s posts.

pub async fn get_my_replies( &self, opts: Option<&PostsOptions>, ) -> Result<RepliesResponse>

Get the authenticated user’s replies.

pub async fn get_my_mentions( &self, opts: Option<&PostsOptions>, ) -> Result<PostsResponse>

Get posts where the authenticated user is mentioned.

pub async fn get_my_ghost_posts( &self, opts: Option<&PostsOptions>, ) -> Result<PostsResponse>

Get the authenticated user’s ghost posts.

pub async fn get_recently_searched_keywords(&self) -> Result<Vec<RecentSearch>>

Get the authenticated user’s recently searched keywords.

impl Client

pub fn get_auth_url(&self, scopes: &[String]) -> (String, String)

Build the OAuth authorization URL that the user should visit.

scopes overrides the scopes from the client config. Pass an empty slice to use the config defaults. Returns (url, state) — the caller must store state and verify it matches the state query parameter on the OAuth callback to prevent CSRF.

pub async fn get_app_access_token(&self) -> Result<AppAccessTokenResponse>

Get an app access token using client credentials.

This does NOT store the token in the client (matches Go behavior). The caller should use the returned token as needed.

pub fn get_app_access_token_shorthand(&self) -> String

Get an app access token in shorthand format.

Returns "TH|{client_id}|{client_secret}" or an empty string if client_id or client_secret are empty.

pub async fn exchange_code_for_token(&self, code: &str) -> Result<()>

Exchange an authorization code for a short-lived access token.

On success the token is stored via set_token_info.

pub async fn get_long_lived_token(&self) -> Result<()>

Convert the current short-lived token into a long-lived token (60 days).

Requires that the client already holds a valid short-lived token.

pub async fn refresh_token(&self) -> Result<()>

Refresh the current long-lived token, extending its expiry.

The token must still be valid (not expired) to be refreshed.

pub async fn debug_token(&self, input_token: &str) -> Result<DebugTokenResponse>

Inspect a token via the /debug_token endpoint.

pub async fn validate_token(&self) -> Result<()>

Validate the current token locally: non-empty and not expired.

pub async fn ensure_valid_token(&self) -> Result<()>

Validate the current token and auto-refresh if expired.

Only attempts a refresh when the token exists but has expired. Returns the original error for other failures (no token, empty token).

pub async fn get_token_debug_info(&self) -> HashMap<String, String>

Return debug information about the current token.

The access token is masked (first 4 + last 4 characters shown).

pub async fn load_token_from_storage(&self) -> Result<()>

Explicitly reload the token from storage.

pub async fn set_token_from_debug_info( &self, access_token: &str, debug_resp: &DebugTokenResponse, ) -> Result<()>

Store a token built from a previous debug_token response.

Useful for bootstrapping the client from a known-valid token without going through the full OAuth flow again.

impl Client

pub async fn new(config: Config) -> Result<Self>

Create a new client with the given configuration.

pub async fn with_token_storage( config: Config, token_storage: Box<dyn TokenStorage>, ) -> Result<Self>

Create a new client with custom token storage.

pub async fn with_token(config: Config, access_token: &str) -> Result<Self>

Create a client with a pre-existing access token.

Calls the debug_token endpoint to resolve the user ID and exact expiry from the token. Useful for scripts and tests where the token is already known.

pub async fn from_env() -> Result<Self>

Create a client from environment variables.

pub async fn set_token_info(&self, token_info: TokenInfo) -> Result<()>

Set token information (thread-safe).

pub async fn get_token_info(&self) -> Option<TokenInfo>

Get a copy of the current token info.

pub async fn is_authenticated(&self) -> bool

Returns true if the client has a valid access token.

pub async fn is_token_expired(&self) -> bool

Returns true if the current token has expired.

pub async fn is_token_expiring_soon(&self, within: Duration) -> bool

Returns true if the token expires within the given duration.

pub async fn clear_token(&self) -> Result<()>

Clear the current token from the client and storage.

pub async fn access_token(&self) -> String

Get the current access token.

pub fn config(&self) -> &Config

Returns a reference to the client configuration.

pub async fn update_config(self, new_config: Config) -> Result<Client>

Consume this client and create a new one with the given config, preserving the current token state.

pub async fn rate_limit_status(&self) -> Option<RateLimitStatus>

Returns the current rate limit status.

pub async fn is_near_rate_limit(&self, threshold: f64) -> bool

Returns true if we’re close to the rate limit.

pub async fn is_rate_limited(&self) -> bool

Returns true if we’re currently rate-limited by the API.

pub async fn disable_rate_limiting(&self)

Disable rate limiting. Requests will not be throttled.

pub async fn enable_rate_limiting(&self)

Enable rate limiting.

pub async fn wait_for_rate_limit(&self) -> Result<()>

Wait until the rate limiter allows a request.