github-rust 0.2.0

Rust library for GitHub API integration with GraphQL/REST support
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
use crate::error::*;
use crate::github::client::GitHubClient;
use crate::github::graphql::{self, Repository};
use crate::github::{rest, search};

/// REST fallback policy for authenticated repository lookups.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub enum FallbackPolicy {
    /// Preserve every GraphQL error without trying REST.
    Never,
    /// Try REST only when GraphQL returns HTTP 502, 503 or 504.
    #[default]
    OnServerUnavailable,
}

/// 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.
/// Token permissions control access. Quotas vary by API resource and token type.
///
/// # Example
///
/// ```no_run
/// use github_rust::GitHubService;
///
/// # async fn example() -> github_rust::Result<()> {
/// 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);
/// # Ok(())
/// # }
/// ```
pub struct GitHubService {
    /// The underlying HTTP client with connection pooling.
    pub client: GitHubClient,
    fallback_policy: FallbackPolicy,
    pub(crate) fetch_options: super::FetchOptions,
}

impl GitHubService {
    /// 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
    ///
    /// ```no_run
    /// use github_rust::GitHubService;
    ///
    /// let service = GitHubService::new()?;
    /// # Ok::<(), github_rust::GitHubError>(())
    /// ```
    #[must_use = "Creating a service without using it is wasteful"]
    pub fn new() -> Result<Self> {
        let client = GitHubClient::new()?;
        Ok(Self::with_client(client))
    }

    /// Creates a GitHub service with a custom client.
    ///
    /// Useful for testing or when you need custom HTTP configuration.
    #[must_use]
    pub fn with_client(client: GitHubClient) -> Self {
        Self {
            client,
            fallback_policy: FallbackPolicy::default(),
            fetch_options: super::FetchOptions::default(),
        }
    }

    /// Selects which authenticated GraphQL failures may trigger REST.
    /// Anonymous repository lookups always use REST directly.
    #[must_use]
    pub fn with_fallback_policy(mut self, policy: FallbackPolicy) -> Self {
        self.fallback_policy = policy;
        self
    }

    /// Fetches detailed information about a GitHub repository.
    ///
    /// Uses REST directly without a token. Authenticated lookups use GraphQL,
    /// with REST fallback only for HTTP 502/503/504 by default.
    /// Authentication, permission, quota and decoding errors are returned unchanged.
    ///
    /// # 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
    ///
    /// ```no_run
    /// # use github_rust::GitHubService;
    /// # async fn example() -> github_rust::Result<()> {
    /// 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);
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub async fn get_repository_info(&self, owner: &str, name: &str) -> Result<Repository> {
        if !self.client.has_token() {
            return rest::get_repository_info(&self.client, owner, name).await;
        }
        match graphql::get_repository_info(&self.client, owner, name).await {
            Ok(repo) => Ok(repo),
            Err(graphql_error)
                if self.fallback_policy == FallbackPolicy::OnServerUnavailable
                    && matches!(
                        &graphql_error,
                        GitHubError::ApiError {
                            status: 502..=504,
                            ..
                        }
                    ) =>
            {
                tracing::debug!("GraphQL unavailable, trying REST: {graphql_error}");
                rest::get_repository_info(&self.client, owner, name)
                    .await
                    .map_err(|rest_error| GitHubError::FallbackError {
                        graphql: Box::new(graphql_error),
                        rest: Box::new(rest_error),
                    })
            }
            Err(error) => Err(error),
        }
    }

    /// 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
    ///
    /// ```no_run
    /// # use github_rust::GitHubService;
    /// # async fn example() -> github_rust::Result<()> {
    /// 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);
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub async fn search_repositories(
        &self,
        days_back: u32,
        limit: usize,
        language: Option<&str>,
        min_stars: u32,
    ) -> Result<Vec<search::SearchRepository>> {
        search::search_repositories(&self.client, days_back, limit, language, min_stars).await
    }

    /// 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
    ///
    /// ```no_run
    /// # use github_rust::GitHubService;
    /// # async fn example() -> github_rust::Result<()> {
    /// 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());
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub async fn check_rate_limit(&self) -> Result<crate::RateLimit> {
        self.client.check_rate_limit().await
    }

    /// Returns separate REST core, search and GraphQL quotas when available.
    pub async fn check_rate_limits(&self) -> Result<crate::RateLimits> {
        self.client.check_rate_limits().await
    }

    /// Returns whether a GitHub token is configured.
    ///
    /// Useful for conditional logic based on authentication status.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use github_rust::GitHubService;
    /// let service = GitHubService::new()?;
    ///
    /// if service.has_token() {
    ///     println!("Token configured");
    /// } else {
    ///     println!("Anonymous access");
    /// }
    /// # Ok::<(), github_rust::GitHubError>(())
    /// ```
    #[must_use]
    pub fn has_token(&self) -> bool {
        self.client.has_token()
    }

    /// Gets all repositories starred by the authenticated user.
    ///
    /// Requires authentication via `GITHUB_TOKEN`.
    ///
    /// # Returns
    ///
    /// List of repository full names in "owner/repo" format.
    /// Returns a pagination error if more than 100 pages must be fetched.
    ///
    /// # Errors
    ///
    /// * [`GitHubError::AuthenticationError`] - No token or invalid token
    /// * [`GitHubError::RateLimitError`] - API rate limit exceeded
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use github_rust::GitHubService;
    /// # async fn example() -> github_rust::Result<()> {
    /// 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);
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub async fn get_user_starred_repositories(&self) -> Result<Vec<String>> {
        rest::get_user_starred_repositories(&self.client).await
    }

    /// Gets the profile of the authenticated user.
    ///
    /// Requires authentication via `GITHUB_TOKEN`.
    ///
    /// # Errors
    ///
    /// * [`GitHubError::AuthenticationError`] - No token or invalid token
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use github_rust::GitHubService;
    /// # async fn example() -> github_rust::Result<()> {
    /// 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);
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub async fn get_user_profile(&self) -> Result<rest::UserProfile> {
        rest::get_user_profile(&self.client).await
    }

    /// Gets users who starred a repository with timestamps.
    ///
    /// Returns stargazers with the date they starred the repository.
    /// Supports pagination. GitHub restricts listing access to repository admins
    /// and collaborators; empty results may also reflect access restrictions.
    ///
    /// # 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
    ///
    /// ```no_run
    /// # use github_rust::GitHubService;
    /// # async fn example() -> github_rust::Result<()> {
    /// 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);
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub async fn get_repository_stargazers(
        &self,
        owner: &str,
        name: &str,
        per_page: Option<u32>,
        page: Option<u32>,
    ) -> Result<Vec<crate::github::types::StargazerWithDate>> {
        rest::get_repository_stargazers(&self.client, owner, name, per_page, page).await
    }
}

impl GitHubService {
    /// Configure limits for account, owned-repository and open-work-item collections.
    pub fn with_fetch_options(mut self, options: super::FetchOptions) -> Result<Self> {
        self.fetch_options = options.validate()?;
        Ok(self)
    }

    /// Fetch the authenticated account and all organizations visible to its token.
    pub async fn get_viewer(&self) -> Result<super::Viewer> {
        super::accounts::viewer(&self.client, self.fetch_options).await
    }

    /// List repositories owned by a user or organization, including visible private,
    /// forked and archived repositories. Results are sorted by full name.
    pub async fn get_owned_repositories(&self, login: &str) -> Result<super::OwnedRepositories> {
        super::accounts::repositories(
            &self.client,
            login,
            self.fetch_options,
            None::<super::pagination::NoProgress<_>>,
        )
        .await
    }

    /// List owned repositories, lending each validated page to an asynchronous callback.
    /// Use `async |page| { ...; Ok(()) }` to borrow the page across await points.
    /// Pages are provisional until this method succeeds. A callback error or dropping
    /// the returned future cancels traversal; no background tasks are spawned.
    /// GitHub does not provide a transactional snapshot across pages.
    pub async fn get_owned_repositories_with_progress<F>(
        &self,
        login: &str,
        progress: F,
    ) -> Result<super::OwnedRepositories>
    where
        F: AsyncFnMut(&super::RepositoryPage) -> Result<()>,
    {
        super::accounts::repositories(&self.client, login, self.fetch_options, Some(progress)).await
    }
}

impl GitHubService {
    /// Fetch every open work item in one repository, sorted by update time descending.
    pub async fn get_open_issues(&self, owner: &str, name: &str) -> Result<Vec<super::Issue>> {
        self.get_open_issues_for_repositories(&[super::RepositoryCoordinates::new(owner, name)?])
            .await
    }
    /// Fetch open work items in explicit repository scopes without rediscovering ownership.
    /// Archived repositories are included if supplied; applications choose their scopes.
    pub async fn get_open_issues_for_repositories(
        &self,
        repositories: &[super::RepositoryCoordinates],
    ) -> Result<Vec<super::Issue>> {
        super::work_items::collect(
            &self.client,
            repositories,
            self.fetch_options,
            None::<super::pagination::NoProgress<_>>,
        )
        .await
    }
    /// Traverse repository scopes with bounded concurrency and lend each page to an async callback.
    /// Empty scopes return immediately without authentication or a callback.
    /// Use `async |page| { ...; Ok(()) }` to borrow the page across await points.
    /// Pages are provisional until the whole call succeeds. Callback errors and dropping
    /// the future cancel traversal. No tasks are spawned. Labels and assignees must fit
    /// their embedded 100-node pages, otherwise this returns a pagination error.
    /// Totals, cursors and repository identity are checked; GitHub offers no snapshot isolation.
    pub async fn get_open_issues_with_progress<F>(
        &self,
        repositories: &[super::RepositoryCoordinates],
        progress: F,
    ) -> Result<Vec<super::Issue>>
    where
        F: AsyncFnMut(&super::WorkItemPage<super::Issue>) -> Result<()>,
    {
        super::work_items::collect(
            &self.client,
            repositories,
            self.fetch_options,
            Some(progress),
        )
        .await
    }
}

impl GitHubService {
    /// Fetch every open work item in one repository, sorted by update time descending.
    pub async fn get_open_pull_requests(
        &self,
        owner: &str,
        name: &str,
    ) -> Result<Vec<super::PullRequest>> {
        self.get_open_pull_requests_for_repositories(&[super::RepositoryCoordinates::new(
            owner, name,
        )?])
        .await
    }
    /// Fetch open work items in explicit repository scopes without rediscovering ownership.
    /// Archived repositories are included if supplied; applications choose their scopes.
    pub async fn get_open_pull_requests_for_repositories(
        &self,
        repositories: &[super::RepositoryCoordinates],
    ) -> Result<Vec<super::PullRequest>> {
        super::work_items::collect(
            &self.client,
            repositories,
            self.fetch_options,
            None::<super::pagination::NoProgress<_>>,
        )
        .await
    }
    /// Traverse repository scopes with bounded concurrency and lend each page to an async callback.
    /// Empty scopes return immediately without authentication or a callback.
    /// Use `async |page| { ...; Ok(()) }` to borrow the page across await points.
    /// Pages are provisional until the whole call succeeds. Callback errors and dropping
    /// the future cancel traversal. No tasks are spawned. Labels and assignees must fit
    /// their embedded 100-node pages, otherwise this returns a pagination error.
    /// Totals, cursors and repository identity are checked; GitHub offers no snapshot isolation.
    pub async fn get_open_pull_requests_with_progress<F>(
        &self,
        repositories: &[super::RepositoryCoordinates],
        progress: F,
    ) -> Result<Vec<super::PullRequest>>
    where
        F: AsyncFnMut(&super::WorkItemPage<super::PullRequest>) -> Result<()>,
    {
        super::work_items::collect(
            &self.client,
            repositories,
            self.fetch_options,
            Some(progress),
        )
        .await
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_github_service_creation() {
        let service = GitHubService::new();
        assert!(service.is_ok());
    }

    #[test]
    fn test_github_service_has_token_detection() {
        let service = GitHubService::new().unwrap();
        // Token detection should work without panicking
        let _has_token = service.has_token();
    }
}