feat: unify the SDK with the Seam SDKs for other languages

[razor-x]

Brings the runtime surface of this SDK up to date. The codegen and release tooling were already in place; the client, auth, error and test layers were not.

Added

• Personal access token authentication, with the seam-workspace header, plus token format validation that rejects a client session token, JWT or publishable key with a specific message instead of letting the server return an opaque 401.
• from_api_key, from_personal_access_token and from_client factories.
• Seam\SeamWithoutWorkspace for the endpoints that take no workspace in scope, exposing only workspaces->list() and workspaces->create().
• Seam\SeamWebhook, verifying incoming webhooks with svix and returning a typed Event.
• Configuration from the environment: SEAM_API_KEY, SEAM_PERSONAL_ACCESS_TOKEN, SEAM_WORKSPACE_ID and SEAM_ENDPOINT, plus the deprecated SEAM_API_URL and both of its warnings. A client can be constructed with no arguments under either authentication method; defining both credential variables at once is ambiguous and raises an InvalidOptionsError.
• Retries, twice by default with exponential backoff, via caseyamcl/guzzle_retry_middleware.
• A 30 second request timeout, covering connecting and reading, configurable with timeout.
• HTTP layer configuration: guzzle_options, retries, timeout, and an injectable client.
• A client level wait_for_action_attempt default, taking a bool or a timeout and polling_interval.
• A test suite covering auth, env, headers, errors, malformed responses, retries, pagination, serialization, action attempts, resources and webhooks, run against @seamapi/fake-seam-connect.
• Psalm, wired into composer lint.

Nested resource classes

A nested class was named after the root resource plus the property, but the base name was never replaced as the recursion descended, so every shape below the first level competed for one name and the first one generated silently won.

device.properties.battery and device.properties.accessory_keypad.battery both resolved to DeviceBattery. The keypad won, so the device battery was generated with only level and $device->properties->battery->status did not exist. The same collapse hit the climate preset metadata, which took the shape of properties.ecobee_metadata and lost climate_ref, is_optimized and owner.

A nested class is now named after its property alone and declared in the namespace of the class that owns it, so the two batteries are Device\Properties\Battery and Device\Properties\AccessoryKeypad\Battery. This also keeps Seam\Resources free of the hundreds of names that existed only to type a property. Where the old code silently overwrote, codegen now throws: on two siblings producing the same class name, on a name PHP reserves as a type, and on nesting deeper than 16 levels.

Merging a discriminated union moved to codegen/lib/merge-properties.ts, shared verbatim with the Ruby SDK, and unions by name recursively rather than taking the first occurrence. A merged property keeps its description only when every variant that documents it agrees, since each variant documents the property for its own case. This drops the description on is_device_error, which claimed the error is not a device error on every variant including the ones where it is.

Fixed

Bugs found in the existing client along the way:

• Responses in the 3xx range were treated as successful (the check was >= 400 rather than outside 200–299).
• The Seam error check accepted any body with a truthy error key. It now requires a JSON content type and string error.type and error.message.
• throw_http_errors let Guzzle throw before the SDK could map the error, making the entire error mapping block unreachable when set. The option is gone; errors always map.
• Malformed JSON silently decoded to null and then failed on property access. The try/catch around json_decode was dead code, since it returns null rather than throwing.
• A non-Seam error response raised an exception built from a fabricated request with a relative URI and no headers. Error mapping is middleware now, so it holds the real one.
• getRequestId() returned "" rather than null when the header was absent, and the fallback error type was unknown rather than unknown_error.
• HttpInvalidInputError never actually overrode the error code — it wrote to a dynamic property because the parent's was private — and the action attempt errors wrote to an undeclared $name property, a PHP 8.2 deprecation CI would have hit on 8.5.
• Paginator::firstPage() indexed its cache unconditionally, and the null cursor guard was unreachable because the parameter was typed non-nullable.

Two more came out of writing the tests: the SEAM_API_KEY environment variable was overriding an explicitly passed personal access token, and Guzzle resolves its handler stack in reverse, so a history middleware pushed by a caller sits outside the retry middleware and cannot observe retries at all, which would have made the retry assertions silently vacuous.

Breaking changes

Covered in the new "Upgrading from 3.x" README section.

• PHP 8.2 or later is required, and svix/svix is a new dependency. PHP 8.1 reached end of life in December 2025.
• The client class is Seam\Seam, replacing Seam\SeamClient.
• The constructor takes named options, so endpoint is no longer the second positional argument, and throw_http_errors is removed.
• The exception classes stay in the Seam\ namespace and now share a Seam\SeamException interface; InvalidOptionsError and InvalidTokenError are new.
• poll_until_ready() is removed in favour of wait_for_action_attempt, which also takes a timeout and polling_interval.
• $seam->client is the Guzzle client, and Seam::request() is removed. Read a body with Seam\Http\Body::decode().
• The $api_key property and the global LTS_VERSION constant are removed. Use Seam\Seam::LTS_VERSION.
• A response in the 3xx range is no longer treated as successful.
• Requests time out after 30 seconds and are retried twice.
• Pagination metadata is a Seam\Pagination rather than a stdClass.
• Nested resource classes are namespaced, so Seam\Resources\DeviceBattery is now Seam\Resources\Device\Properties\Battery.

Notes on the diff

• src/Seam.php is the generated client. PSR-4 requires the file name to match the class, which is why it is not src/SeamClient.php.
• PHPUnit went 9 → 10 because PHPUnit 9 pins nikic/php-parser v4 while Psalm 6 needs v5. The config was migrated to the 10.5 schema.
• composer.json now pins config.platform.php, so the lockfile is resolved against the oldest supported PHP rather than whichever version generated it.
• The CI matrix was 8.0, 8.5; it is now 8.2 through 8.5, so the versions in between are actually exercised.
• Coverage excludes src/Resources and src/Routes, since measuring coverage on generated code only creates pressure to test the generator.
• Endpoint methods are documented as taking named arguments. PHP cannot declare a parameter as name-only, and parameter order comes from the API definition, so a positional call can start binding a value to the wrong parameter after an upgrade.

Verification

Against PHP 8.4 locally:

• composer test — 103 tests, 190 assertions, against a real fake-seam-connect instance
• composer lint — composer validate --strict, php -l, and Psalm, all clean
• npm run lint and npx tsc --noEmit — clean
• npm run generate twice — the second run produces an empty diff, so the generator stays a fixed point as generate.yml requires
• Every README snippet run against the fake, including the paginator, the without-workspace client and a webhook verify round trip

CI covers 8.2, 8.3 and 8.5, which this environment could not exercise.