Modernize client to v2: resource-oriented, typed, full API coverage

Rewrite the TestingBot PHP client (PHP 8.1+) around a resource-grouped
`TestingBot\Client` with a backward-compatible `TestingBot\TestingBotAPI`
facade. The 1.x flat method names/signatures are preserved; the one behaviour
change is that failures now throw typed exceptions instead of returning an
`['error' => ...]` array.

Highlights:
- Full API coverage across 13 resources (tests, builds, storage, tunnels, user,
  team-management, codeless lab tests + suites, screenshots, devices, browsers,
  configuration, jobs).
- Single cURL chokepoint behind HttpClientInterface (timeouts, TLS verify,
  versioned UA, curl_errno -> NetworkException, HTTP-status checking) with a
  mockable seam for tests.
- Typed exception hierarchy (Authentication/NotFound/RateLimit/Api/Network).
- Replace PHP8-fatal mime_content_type() with ext-fileinfo.
- PSR-4 autoload; drop bogus runtime deps (phpunit-selenium, paratest, appium);
  type=library; add phpstan (L8), php-cs-fixer (PSR-12), .editorconfig.
- 86 unit tests via FakeHttpClient (no network) + gated live integration suite.
- GitHub Actions: CI matrix PHP 8.1-8.4 + token-free tag-driven release workflow.
- Rewritten README, CHANGELOG, CLAUDE.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jochen-testingbot

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{yml,yaml,json,neon}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

.github/workflows/dependency-review.yml

@@ -15,6 +15,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: 'Checkout Repository'
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: 'Dependency Review'
-        uses: actions/dependency-review-action@v1
+        uses: actions/dependency-review-action@v4

.github/workflows/release.yml

@@ -0,0 +1,87 @@
+name: Release
+
+# Cutting a release is just pushing a version tag:
+#
+#     git tag 2.0.0 && git push origin 2.0.0
+#
+# Packagist picks up the new version automatically through its GitHub
+# integration (no token needed). This workflow only validates the tag and
+# publishes a GitHub Release, using the built-in GITHUB_TOKEN — there are no
+# secrets to configure.
+
+on:
+  push:
+    tags:
+      - '[0-9]+.[0-9]+.[0-9]+'
+      - '[0-9]+.[0-9]+.[0-9]+-*'
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+      - 'v[0-9]+.[0-9]+.[0-9]+-*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Publish release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+          extensions: curl, json, fileinfo
+          coverage: none
+          tools: composer:v2
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-interaction --no-progress
+
+      - name: Validate composer.json
+        run: composer validate --strict
+
+      - name: Verify the tag matches Client::VERSION
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version="$(php -r 'require "src/Client.php"; echo TestingBot\Client::VERSION;')"
+          if [ "$tag" != "$version" ]; then
+            echo "::error::Tag '$tag' does not match Client::VERSION '$version'. Bump the VERSION constant before tagging."
+            exit 1
+          fi
+          echo "Tag and Client::VERSION agree: $version"
+
+      - name: Coding standards
+        run: composer cs-check
+
+      - name: Static analysis
+        run: composer phpstan
+
+      - name: Unit tests
+        run: composer test
+
+      - name: Extract release notes from CHANGELOG
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          awk -v ver="$version" '
+            $0 ~ "^## \\[" ver "\\]" {flag=1; next}
+            /^## / && flag {flag=0}
+            flag {print}
+          ' CHANGELOG.md > release-notes.md
+          if [ ! -s release-notes.md ]; then
+            echo "No CHANGELOG section found for $version; GitHub will auto-generate notes."
+          fi
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if [ -s release-notes.md ]; then
+            gh release create "$GITHUB_REF_NAME" \
+              --title "$GITHUB_REF_NAME" \
+              --notes-file release-notes.md
+          else
+            gh release create "$GITHUB_REF_NAME" \
+              --title "$GITHUB_REF_NAME" \
+              --generate-notes
+          fi

.github/workflows/test.yml

@@ -1,19 +1,61 @@
-name: Test Changes
+name: CI
 
 on: [push, pull_request]
 
 jobs:
-  test:
+  unit:
+    name: Unit (PHP ${{ matrix.php }})
     runs-on: ubuntu-latest
-    name: PHP test
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['8.1', '8.2', '8.3', '8.4']
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: curl, json, fileinfo
+          coverage: none
+          tools: composer:v2
+
       - name: Install dependencies
-        uses: php-actions/composer@v5
-      - name: PHPUnit tests
-        uses: php-actions/phpunit@v2
+        run: composer install --prefer-dist --no-interaction --no-progress
+
+      - name: Check coding standards
+        run: composer cs-check
+
+      - name: Static analysis
+        run: composer phpstan
+
+      - name: Unit tests
+        run: composer test
+
+  integration:
+    name: Integration (live API)
+    runs-on: ubuntu-latest
+    # Only run where the repository secrets are available: pushes to the main
+    # branch and tags. Pull requests (including from forks) skip the live suite.
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/'))
+    needs: unit
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+          extensions: curl, json, fileinfo
+          coverage: none
+          tools: composer:v2
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-interaction --no-progress
+
+      - name: Integration tests
         env:
           TB_KEY: ${{ secrets.TB_KEY }}
           TB_SECRET: ${{ secrets.TB_SECRET }}
-        with:
-          configuration: tests/phpunit.xml
+        run: composer test:integration

.gitignore

@@ -1,2 +1,7 @@
 composer.phar
+composer.lock
 vendor/
+.phpunit.result.cache
+.phpunit.cache
+.php-cs-fixer.cache
+.phpstan.cache

.php-cs-fixer.dist.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+$finder = PhpCsFixer\Finder::create()
+    ->in([__DIR__ . '/src', __DIR__ . '/tests']);
+
+return (new PhpCsFixer\Config())
+    ->setRiskyAllowed(true)
+    ->setRules([
+        '@PSR12' => true,
+        'declare_strict_types' => true,
+        'array_syntax' => ['syntax' => 'short'],
+        'no_unused_imports' => true,
+        'ordered_imports' => ['sort_algorithm' => 'alpha'],
+        'single_quote' => true,
+        'trailing_comma_in_multiline' => true,
+    ])
+    ->setFinder($finder);

.travis.yml

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0]
+
+A full modernization of the client. The 1.x flat method surface is preserved
+(see *Backward compatibility* below), but the internals, error handling and
+minimum PHP version have changed.
+
+### Added
+- New resource-oriented entry point `TestingBot\Client` with grouped accessors:
+  `tests()`, `builds()`, `storage()`, `tunnels()`, `user()`, `teamManagement()`,
+  `lab()`, `labSuites()`, `screenshots()`, `devices()`, `browsers()`,
+  `configuration()`, `jobs()`.
+- Full API coverage: full test CRUD, user info/keys/update, team management
+  (sub-accounts), codeless tests **and** suites, screenshots, tunnel
+  create/get/list, devices, browsers, configuration IP ranges, and a job poller
+  (`jobs()->waitForCompletion()`).
+- Typed exception hierarchy: `AuthenticationException` (401/403),
+  `NotFoundException` (404), `RateLimitException` (429, with `getRetryAfter()`),
+  `ApiException` (other non-2xx, with `getStatusCode()`/`getResponseBody()`),
+  and `NetworkException` (transport failures). All implement
+  `TestingBot\Exception\TestingBotExceptionInterface`.
+- A mockable transport seam (`TestingBot\Http\HttpClientInterface`) so the
+  client can be unit-tested without hitting the live API.
+- HTTP timeouts, explicit TLS verification, a versioned User-Agent, and
+  transport-level error detection.
+- `Client::request()` low-level escape hatch for endpoints not yet wrapped.
+- `phpstan` (level 8), `php-cs-fixer` (PSR-12), `.editorconfig`, and a GitHub
+  Actions matrix across PHP 8.1–8.4.
+
+### Changed
+- **Errors now throw exceptions** instead of returning an array containing an
+  `error` key. Wrap calls in `try/catch` (see README "Migrating from 1.x").
+- Minimum PHP version is now **8.1**.
+- Autoloading moved from PSR-0 to **PSR-4** (the `TestingBot\TestingBotAPI`
+  class name is unchanged).
+- `composer.json` `type` corrected to `library`.
+- `TestingBotAPI::createLabTest()` now wraps `$extras` keys as plain field
+  names automatically (no need to pre-wrap them as `test[...]`).
+- `TestingBotAPI::modifyLabTestSteps()` keeps sending the exact legacy body for
+  compatibility; prefer `client()->lab()->setSteps()`, which URL-encodes values.
+
+### Fixed
+- File uploads no longer fatal on PHP 8: `mime_content_type()` replaced with the
+  `fileinfo` extension.
+- Network failures (DNS, timeout, TLS) are surfaced as `NetworkException`
+  instead of being silently swallowed as `null`.
+
+### Removed
+- The bogus runtime dependencies `phpunit/phpunit-selenium`,
+  `brianium/paratest` and `appium/php-client` (they were never used by the
+  client and forced unnecessary installs).
+- The obsolete `.travis.yml` (CI runs on GitHub Actions).
+
+### Backward compatibility
+All 1.x `TestingBotAPI` methods keep their names and signatures and continue to
+work. The behavioural change to be aware of is that failures now throw instead
+of returning `['error' => ...]`. Argument-validation now throws
+`TestingBot\Exception\InvalidArgumentException`, a subclass of the SPL
+`\InvalidArgumentException`, so existing `catch (\Exception $e)` blocks still
+catch it.
+
+## [1.0.3] and earlier
+
+See the git history for changes prior to the 2.0 rewrite.

CHANGELOG.md

@@ -0,0 +1,40 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+PHP client library for the [TestingBot REST API](https://testingbot.com/support/api), distributed via Composer as `testingbot/testingbot-php`. Targets **PHP 8.1+**, PSR-4 autoloaded under `TestingBot\` → `src/`.
+
+There are two entry points:
+- `TestingBot\Client` (`src/Client.php`) — the modern, resource-grouped client. New work goes here.
+- `TestingBot\TestingBotAPI` (`src/TestingBotAPI.php`) — a thin backward-compatible facade that preserves the 1.x flat method names and delegates to `Client`.
+
+## Commands
+
+```bash
+composer install
+composer test            # unit suite — no credentials, no network (uses FakeHttpClient)
+composer phpstan         # static analysis, level 8
+composer cs-check        # PSR-12 dry-run; composer cs-fix to apply
+composer test:integration   # live API; needs TB_KEY / TB_SECRET, otherwise skipped
+vendor/bin/phpunit --filter testUpdateWrapsFields   # run a single test
+```
+
+PHP/Composer are provided via Homebrew (`/opt/homebrew/bin`); add it to `PATH` if `php` isn't found.
+
+## Architecture
+
+Request flow: a resource method builds a `Http\Request` value object and hands it to `AbstractResource::request()` (or `Client::request()` for the raw escape hatch), which sends it through an `Http\HttpClientInterface` and maps the `Http\Response` to a decoded array — or throws.
+
+- **`Http\HttpClientInterface`** is the seam. `Http\CurlHttpClient` is the only class that touches cURL (auth, timeouts, TLS verify, User-Agent, `curl_errno` → `NetworkException`, status via `CURLINFO_RESPONSE_CODE`). Tests inject `tests/Support/FakeHttpClient.php`, which records the `Request` and replays canned `Response`s — this is why the unit suite needs no network. Inject a fake via the optional 4th constructor arg on both `Client` and `TestingBotAPI`.
+- **Resources** (`src/Resource/*.php`) extend `AbstractResource` and each map to one API resource group. Helpers on the base class: `wrap('test', $fields)` for the `test[...]`/`user[...]`/`suite[...]` param convention, `stripAppScheme()` for `tb://` URLs, `paginationQuery()`, and `requireNonEmpty()` for id guards.
+- **Errors throw.** `AbstractResource::request()` throws `ApiException::fromResponse()` on non-2xx, which selects the subclass by status (401/403 → `AuthenticationException`, 404 → `NotFoundException`, 429 → `RateLimitException`, else `ApiException`). All library throwables implement `Exception\TestingBotExceptionInterface`.
+- **Multipart uploads** go through `Http\Multipart::fromFile()` (uses `ext-fileinfo`, not the removed `mime_content_type()`) and are sent through the same `CurlHttpClient` path as everything else — no separate curl handle.
+- **The facade** keeps loose/untyped params on purpose so 1.x callers don't hit `TypeError`s; phpstan's `missingType` rule is ignored for `src/TestingBotAPI.php` only. `modifyLabTestSteps()` deliberately builds the legacy `steps[][...]` raw-string body via `Client::request()` for byte-for-byte compatibility — prefer `lab()->setSteps()` elsewhere.
+
+When adding an endpoint: add a typed method on the relevant `Resource` class that builds a `Request` and returns `$this->request(...)`, add a `FakeHttpClient`-based unit test asserting the request shaping, and (if it was a 1.x method) a delegating method on the facade.
+
+## Source of truth
+
+The canonical API surface is the Grape definition at `/Users/jochen/projects/web/app/api/testingbot/api.rb`. All endpoints accept HTTP Basic auth (`key:secret`) and a generic `?omit=a,b,c` field filter; list endpoints return `{data, meta:{offset,count,total}}`.