feat: add Checks API, file contents, and Laravel 13 support

composer.json

@@ -28,7 +28,7 @@
     "require": {
         "php": "^8.2|^8.3|^8.4",
         "firebase/php-jwt": "^7.0",
-        "illuminate/contracts": "^11.0||^12.0",
+        "illuminate/contracts": "^11.0||^12.0||^13.0",
         "jordanpartridge/conduit-interfaces": "^1.1",
         "saloonphp/saloon": "^3.10",
         "spatie/laravel-package-tools": "^1.16|^2.0"

phpstan-baseline.neon

@@ -0,0 +1,21 @@
+parameters:
+	ignoreErrors:
+		-
+			message: "#^Instantiated class JordanPartridge\\\\GithubClient\\\\Exceptions\\\\ResourceNotFoundException not found\\.$#"
+			count: 1
+			path: src/Connectors/GithubConnector.php
+
+		-
+			message: "#^Missing parameter \\$message \\(string\\) in call to JordanPartridge\\\\GithubClient\\\\Exceptions\\\\NetworkException constructor\\.$#"
+			count: 1
+			path: src/Connectors/GithubConnector.php
+
+		-
+			message: "#^Strict comparison using \\=\\=\\= between non\\-falsy\\-string and '' will always evaluate to false\\.$#"
+			count: 1
+			path: src/Connectors/GithubConnector.php
+
+		-
+			message: "#^Unknown parameter \\$reason in call to JordanPartridge\\\\GithubClient\\\\Exceptions\\\\NetworkException constructor\\.$#"
+			count: 1
+			path: src/Connectors/GithubConnector.php

src/Auth/AuthenticationStrategy.php

@@ -2,6 +2,8 @@
 
 namespace JordanPartridge\GithubClient\Auth;
 
+use JordanPartridge\GithubClient\Exceptions\AuthenticationException;
+
 /**
  * Interface for different GitHub authentication strategies.
  */
@@ -15,7 +17,7 @@ public function getAuthorizationHeader(): string;
     /**
      * Validate that the authentication credentials are properly configured.
      *
-     * @throws \JordanPartridge\GithubClient\Exceptions\AuthenticationException
+     * @throws AuthenticationException
      */
     public function validate(): void;
 
@@ -32,7 +34,7 @@ public function needsRefresh(): bool;
     /**
      * Refresh the authentication if needed.
      *
-     * @throws \JordanPartridge\GithubClient\Exceptions\AuthenticationException
+     * @throws AuthenticationException
      */
     public function refresh(): void;
 }

src/Commands/GithubClientCommand.php

@@ -5,6 +5,7 @@
 use Illuminate\Console\Command;
 use JordanPartridge\GithubClient\Facades\Github;
 use JordanPartridge\GithubClient\ValueObjects\Repo;
+use Illuminate\Support\Str;
 
 class GithubClientCommand extends Command
 {
@@ -109,7 +110,7 @@ private function showCommits(): int
                     substr($commit->sha, 0, 8),
                     $commit->commit->author->name,
                     $commit->commit->author->date->format('Y-m-d H:i'),
-                    \Illuminate\Support\Str::limit($commit->commit->message, 50),
+                    Str::limit($commit->commit->message, 50),
                 ];
             }
 

src/Github.php

@@ -9,6 +9,7 @@
 use JordanPartridge\GithubClient\Exceptions\NetworkException;
 use JordanPartridge\GithubClient\Requests\RateLimit\Get;
 use JordanPartridge\GithubClient\Resources\ActionsResource;
+use JordanPartridge\GithubClient\Resources\ChecksResource;
 use JordanPartridge\GithubClient\Resources\CommentsResource;
 use JordanPartridge\GithubClient\Resources\CommitResource;
 use JordanPartridge\GithubClient\Resources\FileResource;
@@ -57,6 +58,11 @@ public function actions(): ActionsResource
         return new ActionsResource($this);
     }
 
+    public function checks(): ChecksResource
+    {
+        return new ChecksResource($this);
+    }
+
     public function issues(): IssuesResource
     {
         return new IssuesResource($this);

src/Requests/Checks/GetCheckRunsForRef.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace JordanPartridge\GithubClient\Requests\Checks;
+
+use Saloon\Enums\Method;
+use Saloon\Http\Request;
+
+class GetCheckRunsForRef extends Request
+{
+    protected Method $method = Method::GET;
+
+    public function __construct(
+        protected string $owner,
+        protected string $repo,
+        protected string $ref,
+        protected ?int $perPage = null,
+        protected ?int $page = null,
+    ) {}
+
+    public function resolveEndpoint(): string
+    {
+        return "/repos/{$this->owner}/{$this->repo}/commits/{$this->ref}/check-runs";
+    }
+
+    protected function defaultQuery(): array
+    {
+        return array_filter([
+            'per_page' => $this->perPage,
+            'page' => $this->page,
+        ], fn ($value) => $value !== null);
+    }
+}

src/Requests/Checks/GetCombinedStatus.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace JordanPartridge\GithubClient\Requests\Checks;
+
+use Saloon\Enums\Method;
+use Saloon\Http\Request;
+
+class GetCombinedStatus extends Request
+{
+    protected Method $method = Method::GET;
+
+    public function __construct(
+        protected string $owner,
+        protected string $repo,
+        protected string $ref,
+    ) {}
+
+    public function resolveEndpoint(): string
+    {
+        return "/repos/{$this->owner}/{$this->repo}/commits/{$this->ref}/status";
+    }
+}

src/Requests/Files/GetContents.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace JordanPartridge\GithubClient\Requests\Files;
+
+use Saloon\Enums\Method;
+use Saloon\Http\Request;
+
+class GetContents extends Request
+{
+    protected Method $method = Method::GET;
+
+    public function __construct(
+        protected string $owner,
+        protected string $repo,
+        protected string $path,
+        protected ?string $ref = null,
+    ) {}
+
+    public function resolveEndpoint(): string
+    {
+        return "/repos/{$this->owner}/{$this->repo}/contents/{$this->path}";
+    }
+
+    protected function defaultQuery(): array
+    {
+        return array_filter([
+            'ref' => $this->ref,
+        ], fn ($value) => $value !== null);
+    }
+}

src/Resources/ChecksResource.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace JordanPartridge\GithubClient\Resources;
+
+use JordanPartridge\GithubClient\Requests\Checks\GetCheckRunsForRef;
+use JordanPartridge\GithubClient\Requests\Checks\GetCombinedStatus;
+
+readonly class ChecksResource extends BaseResource
+{
+    /**
+     * Get check runs for a commit reference (SHA, branch, or tag).
+     *
+     * @return array{total_count: int, check_runs: array<int, array<string, mixed>>}
+     */
+    public function forRef(string $owner, string $repo, string $ref): array
+    {
+        $response = $this->github()->connector()->send(
+            new GetCheckRunsForRef($owner, $repo, $ref),
+        );
+
+        return $response->json();
+    }
+
+    /**
+     * Get the combined commit status for a reference.
+     *
+     * Returns the overall state (success, failure, pending) and individual statuses.
+     *
+     * @return array{state: string, statuses: array<int, array<string, mixed>>, total_count: int}
+     */
+    public function combinedStatus(string $owner, string $repo, string $ref): array
+    {
+        $response = $this->github()->connector()->send(
+            new GetCombinedStatus($owner, $repo, $ref),
+        );
+
+        return $response->json();
+    }
+
+    /**
+     * Check if all checks pass for a given ref.
+     */
+    public function allPassing(string $owner, string $repo, string $ref): bool
+    {
+        $checkRuns = $this->forRef($owner, $repo, $ref);
+
+        if (empty($checkRuns['check_runs'])) {
+            return true;
+        }
+
+        foreach ($checkRuns['check_runs'] as $run) {
+            if ($run['status'] !== 'completed') {
+                return false;
+            }
+
+            if ($run['conclusion'] !== 'success' && $run['conclusion'] !== 'skipped') {
+                return false;
+            }
+        }
+
+        return true;
+    }
+}

src/Resources/FileResource.php

@@ -3,6 +3,7 @@
 namespace JordanPartridge\GithubClient\Resources;
 
 use InvalidArgumentException;
+use JordanPartridge\GithubClient\Requests\Files\GetContents;
 use JordanPartridge\GithubClient\Requests\Files\Index;
 use JordanPartridge\GithubClient\ValueObjects\Repo;
 use Saloon\Http\Response;
@@ -19,4 +20,32 @@ public function all(string $repo_name, string $commit_sha): Response
 
         return $this->github()->connector()->send(new Index($repo->fullName(), $commit_sha));
     }
+
+    /**
+     * Get the contents of a file at a specific ref (branch, tag, or SHA).
+     *
+     * @return array{name: string, path: string, sha: string, size: int, content: string, encoding: string}
+     */
+    public function contents(string $owner, string $repo, string $path, ?string $ref = null): array
+    {
+        $response = $this->github()->connector()->send(
+            new GetContents($owner, $repo, $path, $ref),
+        );
+
+        return $response->json();
+    }
+
+    /**
+     * Get the decoded contents of a file at a specific ref.
+     */
+    public function getContent(string $owner, string $repo, string $path, ?string $ref = null): string
+    {
+        $data = $this->contents($owner, $repo, $path, $ref);
+
+        if ($data['encoding'] === 'base64') {
+            return base64_decode($data['content']);
+        }
+
+        return $data['content'];
+    }
 }

src/Resources/PullRequestResource.php

@@ -25,6 +25,7 @@
 use JordanPartridge\GithubClient\Requests\Pulls\Reviews;
 use JordanPartridge\GithubClient\Requests\Pulls\Update;
 use JordanPartridge\GithubClient\Requests\Pulls\UpdateComment;
+use Illuminate\Support\Collection;
 
 readonly class PullRequestResource extends BaseResource
 {
@@ -99,7 +100,7 @@ public function reviews(
         string $owner,
         string $repo,
         int $number,
-    ): \Illuminate\Support\Collection {
+    ): Collection {
         $response = $this->github()->connector()->send(new Reviews("{$owner}/{$repo}", $number));
 
         return $response->dto();

tests/ArchTest.php

@@ -1,6 +1,7 @@
 <?php
 
 use JordanPartridge\GithubClient\Resources\BaseResource;
+use Saloon\Http\Request;
 
 describe('General', function () {
     it('will not use debugging functions', function () {
@@ -15,6 +16,6 @@
 
 describe('Requests', function () {
     arch('requests extend the base resource', function () {
-        expect('JordanPartridge\GithubClient\Requests')->toExtend(\Saloon\Http\Request::class);
+        expect('JordanPartridge\GithubClient\Requests')->toExtend(Request::class);
     });
 });

tests/AuthenticationTest.php

@@ -5,6 +5,7 @@
 use JordanPartridge\GithubClient\Facades\Github;
 use Saloon\Http\Faking\MockClient;
 use Saloon\Http\Faking\MockResponse;
+use JordanPartridge\GithubClient\Data\Repos\RepoData;
 
 describe('Authentication improvements', function () {
     it('allows unauthenticated requests for public repositories', function () {
@@ -168,12 +169,12 @@
         $connector->withMockClient($mockClient);
 
         // Create Github instance with unauthenticated connector
-        $github = new \JordanPartridge\GithubClient\Github($connector);
+        $github = new JordanPartridge\GithubClient\Github($connector);
 
         // Should be able to get public repo without auth
         $repo = $github->getRepo('owner/public-repo');
 
-        expect($repo)->toBeInstanceOf(\JordanPartridge\GithubClient\Data\Repos\RepoData::class)
+        expect($repo)->toBeInstanceOf(RepoData::class)
             ->and($repo->name)->toBe('public-repo')
             ->and($repo->private)->toBeFalse();
     });

tests/CommitResourceTest.php

@@ -16,7 +16,7 @@
     ]);
 
     Github::connector()->withMockClient($mockClient);
-    $this->resource = new CommitResource(app(\JordanPartridge\GithubClient\Github::class));
+    $this->resource = new CommitResource(app(JordanPartridge\GithubClient\Github::class));
 });
 
 it('can fetch all commits for a repository', function () {

tests/DTOPatternTest.php

@@ -3,6 +3,7 @@
 use JordanPartridge\GithubClient\Data\Pulls\PullRequestDetailDTO;
 use JordanPartridge\GithubClient\Data\Pulls\PullRequestDTOFactory;
 use JordanPartridge\GithubClient\Data\Pulls\PullRequestSummaryDTO;
+use JordanPartridge\GithubClient\Data\Pulls\PullRequestDTO;
 
 describe('DTO Pattern: Summary vs Detail DTOs', function () {
     beforeEach(function () {
@@ -175,7 +176,7 @@
     describe('Backward Compatibility', function () {
         it('maintains compatibility with existing PullRequestDTO usage', function () {
             // The original PullRequestDTO still works exactly as before
-            $originalDto = \JordanPartridge\GithubClient\Data\Pulls\PullRequestDTO::fromApiResponse($this->detailResponseData);
+            $originalDto = PullRequestDTO::fromApiResponse($this->detailResponseData);
 
             expect($originalDto->number)->toBe(47)
                 ->and($originalDto->comments)->toBe(1)

tests/PullRequestsTest.php

@@ -7,6 +7,7 @@
 use JordanPartridge\GithubClient\Facades\Github;
 use Saloon\Http\Faking\MockClient;
 use Saloon\Http\Faking\MockResponse;
+use Illuminate\Support\Collection;
 
 beforeEach(function () {
     config(['github-client.token' => 'fake-token']);
@@ -162,7 +163,7 @@
         $reviews = Github::pullRequests()->reviews('test', 'repo', 1);
 
         expect($reviews)
-            ->toBeInstanceOf(\Illuminate\Support\Collection::class)
+            ->toBeInstanceOf(Collection::class)
             ->and($reviews->isEmpty())->toBeFalse()
             ->and($reviews->first())
             ->toBeInstanceOf(PullRequestReviewDTO::class)