tom_github_api 1.5.0
tom_github_api: ^1.5.0 copied to clipboard
Typed Dart client for the GitHub API — issues, labels, comments, search, workflows, repositories, repository contents, the low-level git data API, and a GraphQL entry point for the surfaces REST does [...]
Changelog #
1.5.0 #
actionsEnabled: whether GitHub Actions is on for a repository (its Actions permission), so a caller can refuse before dispatching a workflow that would never run.latestWorkflowRunandgetWorkflowRun, withGitHubWorkflowRun(id, status, conclusion, creation time, URL, event): find the run a dispatch started and poll it until it completed.
1.4.0 #
GitHubGitIdentityandcreateCommit'sauthorandcommitter: a commit names who wrote and who made it instead of the authenticated user;GitHubGitCommit.author/.committerread them back.FakeGitHubServerrecords a commit's author and committer (FakeCommit.author/.committer), defaulting as GitHub does to the authenticated user (FakeGitHubServer.authenticatedUser) and the author.
1.3.0 #
Added #
-
package:tom_github_api/testing.dart—FakeGitHubServer, an in-memory GitHub (git data with content-addressed objects and the non-fast-forward refusal, contents, issues, labels, comments, search with lagging indexes, refusing a query that names neitheris:issuenoris:pull-requestwith the422GitHub answers it with) behind anhttp.Client, and the cannedrateLimited,secondaryRateLimited,serverErrorandunauthorizedresponses. It was test support of the Webwork app and is now the shared test double for any caller of this client; a separate entry point, so the client links no test double. Addscryptoas a dependency. -
createWebhook/deleteWebhookand theGitHubWebhookmodel — the last REST calls a live suite made through anhttp.Clientof its own. An inactive hook's creation is how a suite asks whether GitHub accepts an event on a repository; the422arrives as aGitHubException. -
GitHubApiClient.credential()and theGitHubCredentialmodel — the token's login, class (classic or fine-grained, read off the presence ofx-oauth-scopes) and a classic token's scopes, from oneGET /user. The fine-grained branch is stated as unverified: no fleet host has held one. -
GitHubHttpClient.getConditionalList— the array form of the conditional GET (If-None-Match,304reported as unmodified and counted), beside the object form.GitHubApiClient.listAllCommentsConditionalreads a whole comment thread conditionally; the entity tag is the first page's and is returned only for a thread that fits in one page. -
A public GraphQL entry point —
GitHubApiClient.graphql(query, {variables, operationName}). The client had posted GraphQL sincetransferIssuelanded, through a private_http.post('/graphql', …)that only that method could reach, so every other GraphQL need in the workspace stood up its ownhttp.Client— a second place handling auth, retries and the rate-limit headers. The REST surface also cannot reach everything: Projects v2 is GraphQL-only, REST Projects classic having been sunset on 2025-04-01.The error handling is shaped by what GitHub actually does rather than by what an HTTP client usually does, because GitHub answers 200 for every error class and
pathis the discriminator:- a field-scoped error (
NOT_FOUND,VALIDATION) arrives withdatapresent, the offending field null andpathnaming it. Every sibling resolved, so it is returned — throwing would discard the half that worked. ReadGitHubGraphQlResponse.fieldErrors. - a query-fatal error (
INSUFFICIENT_SCOPES) arrives with nodatakey at all and nopath. There is nothing to return, so it throwsGitHubGraphQlException. An explicit"data": nullthrows too: nothing resolved is nothing resolved.
There is deliberately no
expectErrorsflag. A flag that suppresses errors is one somebody sets once and forgets, and the shape above already gives a caller both halves. - a field-scoped error (
-
GitHubApiClient.lastGraphQlRateLimit, besidelastRateLimit.REST and GraphQL both answer
x-ratelimit-*and they are different currencies: 5000 requests an hour against 5000 points, where one point covers roughly a hundred nodes. One field for both would let a REST caller read a GraphQL reply's points as requests and conclude the account had spent far less than it had — silently, and only after a GraphQL call had happened to run in between. The budget is routed on the request's own URL, so a future GraphQL caller cannot forget to set a flag. -
GitHubGraphQlCost, read from a document's ownrateLimit { … }field. A different question again from the budget above: what this query asked for, rather than what the account has left. Null when the document did not request it — a zero would assert the query was free.rateLimitdoes not exist onMutation, so a mutation's cost is readable only from the headers, which is the asymmetry the two accessors exist for.
Changed #
transferIssueposts through the public entry point rather than the private one, so it is a caller of the same surface as everything else and an error-class change is one edit rather than two. Its behaviour is unchanged: the mutation has exactly one field, so any error is a failed transfer however GitHub chose to report it.
Fixed #
- The test mock now sets
requeston every response it builds, asBaseClientdoes in production. It was not merely thinner but unfaithful, and it hid behaviour that reads the field.
Documentation #
GitHubSecondaryRateLimitExceptionstates the measured duration of a content-creation block. It said a block was "not something a flush can wait out", from one measurement of a client that kept sending; a client that stops at the first refusal saw it clear in about two minutes.
1.2.0 #
Added #
GitHubApiClient.getRepositoryand theGitHubRepositorymodel. GitHub answers a request for a renamed repository's old name with 200 and the repository's currentfullName, so comparing the two is the only way to tell a live name from a stale one.getDefaultBranchandgetRepositoryNodeIdread through the same call.createUserRepositoryanddeleteRepository. The create takesautoInit, because a repository with no commits refuses every git-data write.GitHubApiClient.requestCounts— requests issued by this client instance, and separately the ones answered304.lastRateLimitis a per-token figure, so two clients sharing a token read each other's traffic through it. A conditional request answered304is not charged, sorequests == notModifiedover a stretch of polling states that the polling was free.- A secondary rate limit is classified.
GitHubSecondaryRateLimitExceptiontells the points throttle from the content-creation block. Both leave the primary quota untouched, so only the response body separates them. GitHubSecondaryRateLimitException.retryAfter— theRetry-AfterGitHub sent, and null when it sent none.- Mutations are paced.
minMutativeIntervalspaces writes, which is what GitHub asks of a client that creates content. GitHubRetryPolicy.jittered, public and static: an additive spread clamped to a ceiling, for a caller that schedules its own waits.
Changed #
GitHubRetryPolicyprefers a statedRetry-Afterover its own exponential backoff for a secondary limit, and spreads both by jitter. An account-wide limit trips every client of the account at once.- Breaking:
GitHubContentWriteResult.treeShais a required field. A contents write answers with the tree it created, and the model dropped it.
1.1.0 #
Added #
GitHubApiClient.git— the git data API: blobs, trees (recursive), commits, refs, and a conditional ref read, so polling an unchanged branch costs no quota. It is what lets a caller land several files as one commit.git.deleteRef, so a caller that creates a branch can remove it.GitHubApiClient.contents— the repository contents API, for reading and writing a single file.GitHubDeviceFlow— OAuth device authorization, so access can be granted without pasting a token.GitHubRetryPolicy— tells a primary rate limit, a secondary rate limit and a server error apart, and waits accordingly.updateComment,deleteCommentandtransferIssue.GitHubIssuecarries the fields the transfer reads back.
1.0.0 #
- Issues, labels, comments, search and workflow dispatch over token authentication, with rate-limit tracking and typed exceptions.