Struct GitHubService 

pub struct GitHubService {
    pub client: GitHubClient,
}

High-level service for GitHub API operations.

GitHubService is the main entry point for interacting with the GitHub API. It provides a simple, ergonomic interface with automatic fallback from GraphQL to REST API when needed.

Authentication

The service automatically detects the GITHUB_TOKEN environment variable.

• With token: 5,000 requests/hour, access to private repos
• Without token: 60 requests/hour, public repos only

Example

use github_rust::GitHubService;

let service = GitHubService::new()?;

// Check authentication status
if service.has_token() {
    println!("Authenticated with higher rate limits");
}

// Get repository information
let repo = service.get_repository_info("rust-lang", "rust").await?;
println!("{} has {} stars", repo.name_with_owner, repo.stargazer_count);

Fields

client: GitHubClient

The underlying HTTP client with connection pooling.

Implementations

impl GitHubService

pub fn new() -> Result<Self>

Creates a new GitHub service with default configuration.

Automatically detects GITHUB_TOKEN from environment variables.

Errors

Returns an error if the HTTP client cannot be initialized (rare, typically indicates system-level TLS or network configuration issues).

Example

use github_rust::GitHubService;

let service = GitHubService::new()?;

pub fn with_client(client: GitHubClient) -> Self

Creates a GitHub service with a custom client.

Useful for testing or when you need custom HTTP configuration.

pub async fn get_repository_info( &self, owner: &str, name: &str, ) -> Result<Repository>

Fetches detailed information about a GitHub repository.

Uses GraphQL API by default for efficiency, automatically falls back to REST API if GraphQL fails (e.g., when no token is provided for certain queries).

Arguments

• owner - Repository owner (username or organization)
• name - Repository name

Returns

Full repository details including stars, forks, language, topics, license, etc.

Errors

• GitHubError::NotFoundError - Repository doesn’t exist or is private without auth
• GitHubError::RateLimitError - API rate limit exceeded
• GitHubError::AccessBlockedError - Repository access blocked by GitHub
• GitHubError::DmcaBlockedError - Repository blocked for legal reasons

Example

let service = GitHubService::new()?;
let repo = service.get_repository_info("microsoft", "vscode").await?;

println!("Name: {}", repo.name_with_owner);
println!("Stars: {}", repo.stargazer_count);
println!("Forks: {}", repo.fork_count);
if let Some(lang) = &repo.primary_language {
    println!("Language: {}", lang.name);
}

pub async fn search_repositories( &self, days_back: u32, limit: usize, language: Option<&str>, min_stars: u32, ) -> Result<Vec<SearchRepository>>

Searches for recently created repositories with filtering options.

Finds repositories created within the specified time period, filtered by language and minimum star count. Results are sorted by stars (descending).

Arguments

• days_back - Search for repos created in the last N days
• limit - Maximum number of results (capped at 1000)
• language - Optional programming language filter (e.g., “rust”, “python”, “C++”)
• min_stars - Minimum number of stars required

Errors

• GitHubError::InvalidInput - Invalid language parameter
• GitHubError::RateLimitError - API rate limit exceeded
• GitHubError::AuthenticationError - Token required for this operation

Example

let service = GitHubService::new()?;

// Find Rust repos created in last 30 days with 50+ stars
let repos = service.search_repositories(
    30,           // days back
    100,          // limit
    Some("rust"), // language
    50,           // min stars
).await?;

for repo in repos {
    println!("{}: {} stars", repo.name_with_owner, repo.stargazer_count);
}

pub async fn check_rate_limit(&self) -> Result<RateLimit>

Checks the current GitHub API rate limit status.

Useful for monitoring API usage and implementing backoff strategies.

Returns

Rate limit information including limit, remaining requests, and reset time.

Example

let service = GitHubService::new()?;
let limits = service.check_rate_limit().await?;

println!("Remaining: {}/{}", limits.remaining, limits.limit);
println!("Resets at: {}", limits.reset_datetime());

if limits.is_exceeded() {
    println!("Rate limited! Wait {:?}", limits.time_until_reset());
}

pub fn has_token(&self) -> bool

Returns whether a GitHub token is configured.

Useful for conditional logic based on authentication status.

Example

let service = GitHubService::new()?;

if service.has_token() {
    println!("Authenticated: 5000 requests/hour");
} else {
    println!("Anonymous: 60 requests/hour");
}

pub async fn get_user_starred_repositories(&self) -> Result<Vec<String>>

Gets all repositories starred by the authenticated user.

Requires authentication via GITHUB_TOKEN.

Returns

List of repository full names in “owner/repo” format. Limited to 10,000 repositories maximum.

Errors

• GitHubError::AuthenticationError - No token or invalid token
• GitHubError::RateLimitError - API rate limit exceeded

Example

let service = GitHubService::new()?;
let starred = service.get_user_starred_repositories().await?;

println!("You have starred {} repositories", starred.len());
for repo in starred.iter().take(5) {
    println!("  - {}", repo);
}

pub async fn get_user_profile(&self) -> Result<UserProfile>

Gets the profile of the authenticated user.

Requires authentication via GITHUB_TOKEN.

Errors

• GitHubError::AuthenticationError - No token or invalid token

Example

let service = GitHubService::new()?;
let profile = service.get_user_profile().await?;

println!("Logged in as: {}", profile.login);
if let Some(name) = profile.name {
    println!("Name: {}", name);
}

pub async fn get_repository_stargazers( &self, owner: &str, name: &str, per_page: Option<u32>, page: Option<u32>, ) -> Result<Vec<StargazerWithDate>>

Gets users who starred a repository with timestamps.

Returns stargazers with the date they starred the repository. Supports pagination for repositories with many stars.

Arguments

• owner - Repository owner
• name - Repository name
• per_page - Results per page (max 100, default 30)
• page - Page number (default 1)

Errors

• GitHubError::NotFoundError - Repository not found
• GitHubError::RateLimitError - API rate limit exceeded

Example

let service = GitHubService::new()?;

// Get first 100 stargazers
let stargazers = service.get_repository_stargazers(
    "rust-lang", "rust",
    Some(100),  // per_page
    Some(1),    // page
).await?;

for sg in stargazers {
    println!("{} starred at {}", sg.user.login, sg.starred_at);
}