feat: support Circle headless APIs

.github/workflows/ci.yml

@@ -30,20 +30,42 @@ jobs:
         uses: php-actions/composer@v6
 
       - name: PHPUnit Tests
-        uses: php-actions/phpunit@v4
-        env:
-          XDEBUG_MODE: coverage
+        run: vendor/bin/phpunit
+
+  coverage:
+    name: Coverage
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.5'
+          coverage: xdebug
+
+      - name: Install Composer Dependencies
+        uses: ramsey/composer-install@v3
+
+      - name: Generate coverage report
+        run: vendor/bin/phpunit --coverage-clover coverage.xml --coverage-text
+
+      - name: Save coverage report
+        uses: actions/upload-artifact@v4
         with:
-          bootstrap: vendor/autoload.php
-          configuration: phpunit.xml
-          php_extensions: xdebug
-          args: tests --coverage-clover ./coverage.xml
+          name: coverage-report
+          path: coverage.xml
 
       - name: Upload to Codecov
-        uses: codecov/codecov-action@v2
+        uses: codecov/codecov-action@v5
         with:
-          token: ${{ secrets.CODE_COV_TOKEN }}
+          use_oidc: true
           files: ./coverage.xml
+          fail_ci_if_error: true
           verbose: true
 
   phpstan:

README.md

@@ -63,6 +63,40 @@ members, spaces, space groups, posts, comments, messages, events, attendees,
 subscriptions, charges, likes, tags, courses, topics, notifications, contacts,
 profile fields, and flagged content.
 
+The SDK also covers every operation currently published in Circle's Admin API
+V2, Headless Auth API, and Headless Member API specifications:
+
+```php
+use AdroSoftware\CircleSoSdk\Admin;
+use AdroSoftware\CircleSoSdk\HeadlessAuth;
+use AdroSoftware\CircleSoSdk\HeadlessMember;
+
+$admin = Admin::make($adminApiToken, version: 2);
+$members = $admin->communityMembers()->all(['page' => 1]);
+
+$auth = HeadlessAuth::make($headlessApiToken);
+$tokens = $auth->tokens()->createGetAnAuthToken([
+    'email' => 'member@example.com',
+]);
+
+$member = HeadlessMember::make($tokens['access_token']);
+$spaces = $member->spaces()->getListOfSpaces();
+```
+
+The unified admin entry point supports both published API versions. Version 2
+is the default, while V1 can be selected explicitly:
+
+```php
+$adminV1 = Admin::make($adminApiToken, version: 1);
+$adminV2 = Admin::make($adminApiToken, version: 2);
+```
+
+The existing `CircleSo::make()` and `AdminV2::make()` entry points remain
+available for backward compatibility.
+
+Each client also exposes `raw()` for newly released Circle routes that are not
+yet represented by a named resource method.
+
 ## License
 
 This package is licensed under the MIT License - see the [LICENSE](https://github.com/adrosoftware/circle-so-api-php-sdk/blob/main/LICENSE) file for details

docs/content/usage/api.md

@@ -105,3 +105,47 @@ $posts = $circleSo->posts()
     ->communityId(123)
     ->all(spaceId: 456);
 ```
+
+## Admin API V2
+
+Use an Admin API token with the V2 client. Its resource methods cover all 171
+operations published in Circle's Admin API V2 specification.
+
+```php
+use AdroSoftware\CircleSoSdk\AdminV2;
+
+$admin = AdminV2::make($adminApiToken);
+
+$members = $admin->communityMembers()->all(['page' => 1]);
+$space = $admin->spaces()->show(123);
+$post = $admin->posts()->create([
+    'space_id' => 123,
+    'name' => 'Welcome',
+    'body' => 'Welcome to the community.',
+]);
+```
+
+## Headless Auth and Member APIs
+
+Create a member access token with the Headless Auth client, then pass that
+access token to the Headless Member client. These clients cover all 4 Auth and
+102 Member operations in Circle's published specifications.
+
+```php
+use AdroSoftware\CircleSoSdk\HeadlessAuth;
+use AdroSoftware\CircleSoSdk\HeadlessMember;
+
+$auth = HeadlessAuth::make($headlessApiToken);
+$tokens = $auth->tokens()->createGetAnAuthToken([
+    'email' => 'member@example.com',
+]);
+
+$member = HeadlessMember::make($tokens['access_token']);
+$spaces = $member->spaces()->getListOfSpaces();
+$notifications = $member->notifications()->getAPaginatedListOfNotifications([
+    'page' => 1,
+]);
+```
+
+All API clients retain the configured response factory. For forward
+compatibility, call `raw()->call($method, $path, $query, $data)` on any client.

src/AbstractClient.php

@@ -43,10 +43,15 @@ public function __construct(
             'User-Agent' => $this->options->getUserAgent(),
             'Content-Type' => 'application/json',
             'Accept' => 'application/json',
-            'Authorization' => "Token {$this->token}",
+            'Authorization' => $this->authorizationHeader(),
         ]);
     }
 
+    protected function authorizationHeader(): string
+    {
+        return "Token {$this->token}";
+    }
+
     public function getHttpClient(?UriInterface $baseUri = null): HttpMethodsClientInterface
     {
         return $this->clientBuilder->getHttpClient([

src/Admin.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AdroSoftware\CircleSoSdk;
+
+abstract class Admin
+{
+    /** @param int $version Admin API version (1 or 2). */
+    public static function make(
+        string $token,
+        ?Options $options = null,
+        int $version = 2,
+    ): CircleSo|AdminV2 {
+        return match ($version) {
+            1 => CircleSo::make($token, ($options ?? new Options())->withApiVersion('v1')),
+            2 => AdminV2::make($token, $options),
+            default => throw new \InvalidArgumentException('Admin API version must be 1 or 2.'),
+        };
+    }
+}