github-rust 0.2.0

Rust library for GitHub API integration with GraphQL/REST support
Documentation
# github-rust

An async Rust library for GitHub accounts, repositories, open issues and pull requests, search and stargazer access through REST and GraphQL.

## Installation

Requires Rust 1.92 or later (edition 2024).

```toml
[dependencies]
github-rust = { git = "https://github.com/davlgd/github-rust" }
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
```

## Quick start

```rust
use github_rust::{GitHubService, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let service = GitHubService::new()?;
    let repo = service.get_repository_info("rust-lang", "rust").await?;
    println!("{}: {} stars", repo.name_with_owner, repo.stargazer_count);
    println!("Node ID: {}", repo.node_id);
    if let Some(id) = repo.database_id {
        println!("Database ID: {id}");
    }
    if let Some(count) = repo.open_issues() {
        println!("Open issues: {count}");
    }
    Ok(())
}
```

Without a token, repository lookups use REST directly. With a token, they use GraphQL and fall back to REST only on HTTP 502, 503 or 504. Authentication, authorization, quota and decoding errors are returned without fallback. A failed fallback retains both causes in `GitHubError::FallbackError`.

## Configuration and authentication

`GitHubService::new()` reads `GITHUB_TOKEN` from the environment:

```bash
export GITHUB_TOKEN="your-token"
```

The library does **not** load `.env` files. Load them in your application if needed.

For explicit configuration, use the builder. It does not read the environment and is anonymous unless a token is supplied:

```rust
use github_rust::{FallbackPolicy, GitHubClient, GitHubService};

fn main() -> github_rust::Result<()> {
let client = GitHubClient::builder()
    .token("your-token".into())
    .build()?;
let service = GitHubService::with_client(client)
    .with_fallback_policy(FallbackPolicy::Never);
Ok(())
}
```

The builder also accepts `rest_url`, `graphql_url`, and an injected `reqwest::Client` through `http_client`. This supports local mocks and GitHub Enterprise endpoints. Configure both URLs for a custom installation; API availability depends on the server version and permissions. Custom endpoints receive the token, so use trusted URLs. An injected transport controls its own timeout, proxy and redirect policy; the default transport has a 30-second request timeout.

The retained token uses `secrecy::SecretString` and is zeroized when dropped. HTTP requests also contain copies of its value in authorization headers; those copies are not covered by this zeroization guarantee. `GitHubClient::client()` exposes the raw transport without the library's authentication headers.

## Repository data

Repository models use ordinary Rust fields and serialize with snake_case keys, independently of the transport's JSON format:

- `node_id` is an opaque string. `database_id` is an optional numeric ID. Do not decode node IDs.
- `watcher_count` counts notification subscribers, independently of `stargazer_count`.
- `open_issue_count` excludes pull requests. It is unavailable from the REST repository response.
- `pull_request_count` includes all states, and `release_count` counts releases. Both are unavailable from the REST repository response.
- An unavailable count is `None`; an observed zero is `Some(0)`.
- `topics` is a `Vec<String>`; `default_branch` is an `Option<String>`.
- `languages` is an optional list of `LanguageUsage { language, bytes }`. A REST 404 for the language breakdown produces `None`. Other failures are returned. GraphQL retrieves up to 100 languages; check `languages_complete` before treating the list as exhaustive.

Helpers include `language()`, `license()`, `license_spdx()`, `topics()`, `owner()`, `default_branch()`, `open_issues()` and `watcher_count()`.

## Accounts, issues and pull requests

These methods require a token. Empty repository batches return an empty list without authentication or callbacks.

| Method | Returns |
| --- | --- |
| `get_viewer()` | Authenticated account and its visible organizations |
| `get_owned_repositories(login)` | Repositories owned by a user or organization |
| `get_open_issues(owner, name)` | Open issues with authors, labels, assignees and comment counts |
| `get_open_pull_requests(owner, name)` | Open PRs, including draft status and review decisions |

Repository inventories include visible private repositories, forks and archives.
For batch calls, select repositories in your application and convert them with `RepositorySummary::coordinates()`.

### Progress

Use `get_open_issues_with_progress()` or `get_open_pull_requests_with_progress()` to process pages as they arrive:

```rust
async fn example(service: &github_rust::GitHubService) -> github_rust::Result<()> {
    let scopes = [github_rust::RepositoryCoordinates::new("rust-lang", "rust")?];
    let issues = service.get_open_issues_with_progress(&scopes, async |page| {
        println!("Received {} issues", page.items.len());
        Ok(())
    }).await?;
    println!("Complete: {} issues", issues.len());
    Ok(())
}
```

- Callbacks borrow pages without copying them and run serially in arrival order.
- Pages remain provisional until the call succeeds. Return an error or drop the future to cancel.
- Final issue and PR lists sort by update time descending, then node ID.
- Use `get_open_*_for_repositories()` when you only need the final list.

See [account_overview.rs](examples/account_overview.rs) for account discovery, repository filtering and batch calls.

### Limits

Configure collection limits with `GitHubService::with_fetch_options()`:

| `FetchOptions` field | Default |
| --- | --- |
| `page_size` | 100 nodes |
| `max_pages` | 500 per connection |
| `max_concurrent_repositories` | 4 per call |

- Changing totals, duplicate IDs, invalid cursors and repository scope changes produce errors.
- Reaching a page cap or receiving incomplete labels or assignees produces a pagination error. Embedded metadata is limited to 100 labels and 100 assignees per item.
- GitHub does not provide a snapshot across pages; concurrent changes may remain undetected.

## Search

Repository search requires a token and uses GraphQL:

```rust
async fn example(service: &github_rust::GitHubService) -> github_rust::Result<()> {
let repos = service.search_repositories(30, 100, Some("Rust"), 50).await?;
for repo in repos {
    println!("{}: {} stars", repo.name_with_owner, repo.stargazer_count);
}
Ok(())
}
```

Search selects public repositories created after the date `days_back` days ago, with at least `min_stars`, ordered by stars descending. It caps results at 1,000 and requests only the number still needed. A zero limit returns an empty list without a request. Invalid dates or language syntax produce `InvalidInput`; missing, repeated or nonprogressing pagination cursors produce `PaginationError`.

## Stargazers and starred repositories

```rust
async fn example(service: &github_rust::GitHubService) -> github_rust::Result<()> {
let stargazers = service.get_repository_stargazers("owner", "repo", Some(100), Some(1)).await?;
for star in stargazers {
    println!("{} starred at {}", star.user.login, star.starred_at);
}
Ok(())
}
```

GitHub [announced restrictions on stargazer listings](https://github.blog/changelog/2026-06-30-upcoming-access-restrictions-to-public-api-endpoints-and-ui-views/) to administrators and collaborators. A public repository alone does not guarantee access: GitHub documents possible empty responses or HTTP 403. This method reflects the server's response and cannot distinguish an access-filtered empty list from a repository with no stars. It is not a general public star-history API.

`per_page` defaults to 30 and is capped at 100; `page` defaults to 1. Zero values are rejected. The first page is not guaranteed to contain the most recent stars.

`get_user_profile()` and `get_user_starred_repositories()` require an authorized token. The starred-repository helper returns repository names and stops after 100 pages. If another page is needed at that point, it returns `PaginationError` instead of returning a silently truncated list.

## Quotas and errors

Use `GitHubError::kind()` for application-facing messages. Raw `Display` output preserves upstream details and should stay in trusted diagnostics.

```rust
async fn example(service: &github_rust::GitHubService) -> github_rust::Result<()> {
let quotas = service.check_rate_limits().await?;
for (resource, limit) in quotas.resources {
    println!("{resource}: {}/{} remaining", limit.remaining, limit.limit);
    println!("Reset: {:?}", limit.reset_datetime());
}
Ok(())
}
```

`check_rate_limit()` is a convenience method for the REST `core` quota. Search and GraphQL have separate quotas; token presence alone does not establish the available allowance. `RateLimit` provides `used()`, `is_exceeded()`, `time_until_reset()` and `reset_datetime()`; an unrepresentable timestamp returns `None` from the last helper.

`RateLimitError` contains `RateLimitDetails`: the HTTP status, resource, remaining allowance, reset timestamp, original `Retry-After`, request ID and GraphQL errors when present. The library does not automatically sleep or retry. Applications can use this metadata to implement a bounded retry policy.

Other errors distinguish authentication, permission denial, unavailable resources, legal restrictions, API status errors, typed GraphQL errors, pagination and response parsing. Transport and decoding errors preserve their original `std::error::Error::source()` chains. GraphQL errors are returned even if the response also includes partial data.

## Development

```bash
cargo fmt --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --all-targets --locked
cargo test --doc --locked
cargo doc --no-deps --locked
```

Tests use local HTTP mocks and do not require a token or contact GitHub. The single live API test is ignored by default; run it explicitly with `cargo test --test github_api_tests test_real_github_api_rate_limit -- --ignored`.

CI checks Rust 1.92 and stable on Linux, plus stable on macOS. Examples:

```bash
cargo run --example basic_usage
cargo run --example search_repositories
cargo run --example stargazers -- owner/repo
```

## License

Apache-2.0.