README

laravel-athena-sdk is a Laravel-first wrapper around Athenahealth's API. It provides a configured connector, resource-style entry points for common API domains, and DTOs for mapping Athena responses into typed PHP objects.

The package is best suited for applications that want a package-native integration layer instead of building raw Saloon requests and response mapping from scratch.

Installation

composer require chrisreedio/laravel-athena-sdk

Publish the package config:

php artisan vendor:publish --tag="laravel-athena-sdk-config"

Set the required Athena credentials in your environment:

ATHENA_BASE_URL=https://api.preview.platform.athenahealth.com
ATHENA_CLIENT_ID=your-client-id
ATHENA_CLIENT_SECRET=your-client-secret
ATHENA_PRACTICE_ID=your-practice-id
ATHENA_LEAVE_UNPROCESSED=false

Configuration

The package currently publishes a config file only. There are no package views or package migrations to publish.

The connector also ships with built-in Athena rate limiting using Saloon's rate-limit plugin. All requests are capped per connector instance to 15 requests per second outside production and 150 requests per second in production. Rate-limit violations fail fast (a RateLimitReachedException will be thrown rather than auto-sleeping and retrying).

The connector authenticates with Athena using the client credentials grant flow and caches the access token under the athena_access_token cache key.

Usage

Instantiate the connector directly:

use ChrisReedIO\AthenaSDK\AthenaConnector;

$athena = new AthenaConnector();

$appointment = $athena->appointments()->get(
    appointmentId: 123456,
);

Or use the facade:

use ChrisReedIO\AthenaSDK\Facades\Athena;

$providers = Athena::providers();

The top-level resources currently exposed by the connector are:

• appointments()
• departments()
• patients()
• providers()
• referringProviders()
• practice()
• encounters()

Public API

The supported Laravel-facing wrapper surface is documented in docs/public-api.md.

That document covers:

• the connector and facade entry points
• the resource methods exposed through AthenaConnector
• the nested resource helpers exposed from those top-level resources

Raw request classes under src/Requests are still available for lower-level use, but they are not the primary API documented in this package.

Local Checks

composer test
composer analyse
composer format:test

Additional Notes

• docs/endpoints.md tracks endpoint coverage work still to be validated.
• composer analyse runs cleanly and is enforced in CI alongside tests and formatting checks.

Changelog

See CHANGELOG.md for release history.

Contributing

See CONTRIBUTING.md for local setup and pull request expectations.

Security

See SECURITY.md for how to report vulnerabilities.

License

Released under the MIT license.