Download the PHP package valksor/typesafe-sdk-php without Composer

typesafe-sdk-php

A modern PHP client for the TypeSafe AI System One API.

[!IMPORTANT] Unofficial and unaffiliated. This project is not created, maintained, endorsed by, or associated with TypeSafe AI in any way. It is an independent, community-maintained SDK that aims for 1:1 feature parity with the official JavaScript and Python SDKs — the same wire contract, environment configuration, retry semantics, request metadata, and typed errors — written in idiomatic, strictly-typed PHP. All product names, logos, and brands are property of their respective owners.

Features

• Typed Noul, Choice, and Score questions and their answers
• Single systemOne() call with typed answer lookup methods
• Optional typed response models via a ResponseModel factory
• Model discovery via $client->models->list()
• Environment-based configuration with explicit overrides
• Configurable per-attempt timeouts and exponential-backoff retries
• Request IDs and raw response metadata on every call
• Injectable Transport (default cURL) for framework integration and tests
• Status-specific typed exceptions
• Strictly typed, PHPStan max level, zero framework dependencies

Install

Requires PHP 8.4 or newer with the curl and json extensions.

Quick start

Set TYPESAFE_API_KEY, then ask typed questions:

Noul, Choice, and Score represent the three question types. Responses keep all answers in SystemOneResponse::$answers and provide typed lookup methods (noul(), choice(), score()). List available models with $client->models->list().

Typed response models

Pass a class-string implementing ResponseModel as responseModel: to receive a typed model of your own instead of a SystemOneResponse. The model's fromSystemOne() factory pulls the answers it cares about into its own properties:

Throw \UnexpectedValueException from fromSystemOne() to signal a validation failure; the SDK rewraps it as a ResponseValidationError carrying the raw response. Any other exception type propagates unchanged, so a genuine bug in your model class is not misreported as a bad response. Unrecognized answer types are ignored, so a future answer type your model does not read causes no failure.

Security: responseModel: must be a trusted, developer-literal class name. Never derive it from request or user input — a dynamic class-string would invoke an arbitrary fromSystemOne() method (type confusion).

Configuration

The Client constructor uses named arguments. Explicit values take precedence over environment variables:

The default timeout is 10 seconds per attempt. The client retries HTTP 408, 429, and 5xx responses, connection errors, and timeouts twice with exponential backoff. Use RetryPolicy for client-wide settings or RequestOptions for a single call. A custom Transport can be injected for framework integration and tests.

Error handling

HTTP failures throw ApiError subclasses:

Status codes map to BadRequestError (400), AuthenticationError (401), PermissionDeniedError (403), NotFoundError (404), ConflictError (409), UnprocessableEntityError (422), RateLimitError (429), and InternalServerError (5xx). Transport-level failures throw APIConnectionError and APITimeoutError. Successful responses with an invalid shape — and responseModel factories that report a validation failure — throw ResponseValidationError, which exposes the raw $response. Avoid logging that body unredacted in production; it echoes the request state, which may contain sensitive data.

Documentation

• API wire contract: TypeSafe API docs

Testing

Live integration tests are opt-in and read-only (they exercise GET /v1/models):

Releases

This SDK tracks the same release version line as the official JavaScript and Python SDKs. Client::VERSION, the latest changelog entry, and the Git tag must all match exactly — for example, release 0.6.0 with tag v0.6.0. See docs/changelog.md.

CI tests PHP 8.4 and 8.5. The publish workflow can be run manually as a dry run; pushing the matching vX.Y.Z tag from the default branch creates a tested Composer archive and GitHub Release. Configure the package's Packagist GitHub integration so Packagist consumes that same tag automatically.

License

MIT