feat: ESI rate-limit support + typed SDK with OAS3 generator

.github/workflows/formats.yml

@@ -0,0 +1,34 @@
+name: Formats
+
+on:
+  push:
+    paths:
+      - '**.php'
+      - 'composer.json'
+  pull_request:
+    branches: [ 3.x, 4.x ]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2 #https://github.com/shivammathur/setup-php
+        with:
+          php-version: '8.3'
+
+      - name: Install Composer dependencies
+        run: composer update --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
+
+      - name: Coding Style Checks
+        run: composer test:lint
+
+      - name: Type Checks
+        run: composer test:types
+
+      - name: Type Coverage Checks
+        run: composer test:type-coverage

.github/workflows/tests.yml

@@ -0,0 +1,24 @@
+name: Tests
+
+on:
+  push:
+    branches: [ 2.x, 3.x, 4.x ]
+  pull_request:
+    branches: [ 2.x, 3.x, 4.x ]
+
+jobs:
+  ci:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Setup PHP, with composer and extensions
+      uses: shivammathur/setup-php@v2 #https://github.com/shivammathur/setup-php
+      with:
+        php-version: '8.3'
+        coverage: xdebug
+    - name: Install Dependencies
+      run: composer install --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
+    - name: Run tests with coverage
+      run: vendor/bin/pest --coverage --ci --min=100

.gitignore

@@ -2,10 +2,12 @@
 .php_cs
 .php_cs.cache
 .phpunit.result.cache
+.phpunit.cache
 build
 composer.lock
 coverage
 docs
+logs
 phpunit.xml
 vendor
 node_modules

README.md

@@ -1,12 +1,19 @@
 # Esi-Client
 
-[![Latest Version on Packagist](https://img.shields.io/packagist/v/seatplus/esi-client.svg?style=flat-square)](https://packagist.org/packages/seatplus/esi-client)
-[![GitHub Tests Action Status](https://img.shields.io/github/workflow/status/seatplus/esi-client/run-tests?label=tests)](https://github.com/seatplus/esi-client/actions?query=workflow%3Arun-tests+branch%3Amain)
-[![GitHub Code Style Action Status](https://img.shields.io/github/workflow/status/seatplus/esi-client/Check%20&%20fix%20styling?label=code%20style)](https://github.com/seatplus/esi-client/actions?query=workflow%3A"Check+%26+fix+styling"+branch%3Amain)
-[![Total Downloads](https://img.shields.io/packagist/dt/seatplus/esi-client.svg?style=flat-square)](https://packagist.org/packages/seatplus/esi-client)
+[![Latest Stable Version](https://poser.pugx.org/seatplus/esi-client/v/stable)](https://packagist.org/packages/seatplus/esi-client)
+[![Tests](https://github.com/seatplus/esi-client/actions/workflows/tests.yml/badge.svg)](https://github.com/seatplus/esi-client/actions/workflows/tests.yml)
+[![Formats](https://github.com/seatplus/esi-client/actions/workflows/formats.yml/badge.svg)](https://github.com/seatplus/esi-client/actions/workflows/formats.yml)
+[![Maintainability](https://api.codeclimate.com/v1/badges/642d3b3ca41e7cc3cd4f/maintainability)](https://codeclimate.com/github/seatplus/esi-client/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/642d3b3ca41e7cc3cd4f/test_coverage)](https://codeclimate.com/github/seatplus/esi-client/test_coverage)
+[![Total Downloads](https://poser.pugx.org/seatplus/esi-client/downloads)](https://packagist.org/packages/seatplus/esi-client)
+[![License](https://poser.pugx.org/seatplus/esi-client/license)](https://packagist.org/packages/seatplus/esi-client)
 
 A standalone ESI (Eve Swagger Interface) Client Library using kevinrob/guzzle-cache-middleware.
 
+> **ESI compatibility date:** This branch of `esi-client` targets ESI compatibility date **`2025-12-16`** and forward.
+> Responses DTOs are sourced from [`seatplus/esi-schema`](https://github.com/seatplus/esi-schema) (`1.x`).
+> If CCP publishes a new breaking compatibility date, a new major version of both packages will be released.
+
 ## Installation
 
 You can install the package via composer:
@@ -18,19 +25,58 @@ composer require seatplus/esi-client
 
 ## Usage
 
+### Typed SDK (recommended)
+
+The SDK exposes typed resource methods. Single-object endpoints return the DTO directly (a subclass of `AbstractEsiDto`); paginated list endpoints return `EsiResult<array<T>>`.
+
 ```php
-$esi = new Seatplus\EsiClient\EsiClient();
+use Seatplus\EsiClient\EsiClient;
+
+$sdk = new EsiClient();
+
+// Single object — returns AllianceDetail directly
+$alliance = $sdk->alliance()->getAlliancesAllianceId(99000006);
+echo $alliance->name;          // typed readonly string
+echo $alliance->ticker;
+$alliance->isCachedLoad;       // bool — true if served from RFC 7234 cache
+
+// Authenticated endpoint — returns CharactersDetail directly
+$character = $sdk->withToken($accessToken)->characters()->getCharactersCharacterId(95725047);
+echo $character->name;
+
+// Paginated list — returns EsiResult (pages metadata needed)
+$result = $sdk->withToken($accessToken)->assets()->getCharactersCharacterIdAssets(95725047, page: 1);
+echo $result->pages;           // total pages from X-Pages header
+foreach ($result->data as $asset) {
+    echo $asset->item_id;      // typed readonly int
+}
+```
 
-$esi->setVersion('v5'); // if you do not set a version, esi-client is using '/latest'
+### Low-level transport
 
-// make a call
-$character_info = $esi->invoke('get', '/characters/{character_id}/', [
+```php
+$esi = new EsiClient();
+
+// make a call — returns EsiResponse
+$response = $esi->invoke('get', '/characters/{character_id}/', [
     'character_id' => 95725047,
 ]);
 
-echo $character_info;
+// $response->data    — stdClass decoded from the JSON body
+// $response->pages   — total pages (from X-Pages header, or 1)
+// $response->isCachedLoad() — true if served from RFC 7234 cache
 ```
 
+### Rate limiting
+
+ESI enforces a **1800-token / 15-minute** rolling window (one token consumed per request,
+irrespective of response code). `esi-client` itself does not throttle — rate limiting is
+handled by the consumer layer (`eveapi`) using Laravel Horizon throttle middleware on each
+queued job.
+
+If the HTTP client receives a `420 Error Limited` response, the request is retried with
+exponential backoff as configured on the job.
+
 ## Testing
 
 ```bash

composer.json

@@ -23,21 +23,26 @@
         }
     ],
     "require": {
-        "php": "^8.0",
+        "php": "^8.3",
         "ext-json": "*",
-        "firebase/php-jwt": "^5.4",
+        "firebase/php-jwt": "^7.0",
         "kevinrob/guzzle-cache-middleware": "^4.0",
-        "nesbot/carbon": "^2.53",
-        "spatie/data-transfer-object": "^3.7"
+        "monolog/monolog": "^3.7",
+        "nesbot/carbon": "^3.0",
+        "seatplus/esi-schema": "^1.1"
     },
     "require-dev": {
+        "ext-openssl": "*",
         "fzaninotto/faker": "^1.5",
-        "illuminate/cache": "^8.60",
-        "mockery/mockery": "^1.4",
-        "nunomaduro/collision": "^5.3",
-        "pestphp/pest-plugin-laravel": "^1.1",
+        "illuminate/cache": "^11.23",
+        "laravel/pint": "^1.17",
         "mikey179/vfsstream": "^1",
-        "ext-openssl": "*"
+        "mockery/mockery": "^1.4",
+        "nunomaduro/collision": "^8.0",
+        "pestphp/pest": "^4.0",
+        "pestphp/pest-plugin-type-coverage": "^4.0",
+        "phpstan/phpstan": "^2.1.46",
+        "rector/rector": "^2.0"
     },
     "autoload": {
         "psr-4": {
@@ -51,15 +56,23 @@
         }
     },
     "scripts": {
-      "test": "./vendor/bin/pest",
-      "test-coverage": "XDEBUG_MODE=coverage ./vendor/bin/pest --coverage"
+        "lint": "vendor/bin/pint",
+        "test:lint": "vendor/bin/pint --test",
+        "test:types": "vendor/bin/phpstan --ansi",
+        "test:type-coverage": "vendor/bin/pest --type-coverage --min=100",
+        "test:unit": "vendor/bin/pest --colors=always",
+        "test:unit-coverage": "XDEBUG_MODE=coverage vendor/bin/pest --coverage --coverage-html=build/coverage --coverage-clover=build/logs/clover.xml --colors=always",
+        "test": [
+            "@test:lint",
+            "@test:types",
+            "@test:type-coverage",
+            "@test:unit"
+        ]
     },
     "config": {
         "sort-packages": true,
         "allow-plugins": {
             "pestphp/pest-plugin": true
         }
-    },
-    "minimum-stability": "dev",
-    "prefer-stable": true
+    }
 }

phpstan.neon.dist

@@ -0,0 +1,8 @@
+parameters:
+    editorUrl: 'phpstorm://open?file=%%file%%&line=%%line%%'
+    level: 4
+    paths:
+        - src
+    tmpDir: build/phpstan
+
+

phpunit.xml.dist

@@ -1,39 +1,16 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit
-    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
-    backupGlobals="false"
-    backupStaticAttributes="false"
-    bootstrap="vendor/autoload.php"
-    colors="true"
-    convertErrorsToExceptions="true"
-    convertNoticesToExceptions="true"
-    convertWarningsToExceptions="true"
-    processIsolation="false"
-    stopOnFailure="false"
-    executionOrder="random"
-    failOnWarning="true"
-    failOnRisky="true"
-    failOnEmptyTestSuite="true"
-    beStrictAboutOutputDuringTests="true"
-    verbose="true"
->
-    <testsuites>
-        <testsuite name="Seatplus Test Suite">
-            <directory>tests</directory>
-        </testsuite>
-    </testsuites>
-    <coverage>
-        <include>
-            <directory suffix=".php">./src</directory>
-        </include>
-        <report>
-            <html outputDirectory="build/coverage"/>
-            <text outputFile="build/coverage.txt"/>
-            <clover outputFile="build/logs/clover.xml"/>
-        </report>
-    </coverage>
-    <logging>
-        <junit outputFile="build/report.junit.xml"/>
-    </logging>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/12.5/phpunit.xsd" backupGlobals="false" bootstrap="vendor/autoload.php" colors="true" processIsolation="false" stopOnFailure="false" executionOrder="random" failOnWarning="false" failOnRisky="true" failOnEmptyTestSuite="true" beStrictAboutOutputDuringTests="true" cacheDirectory=".phpunit.cache" backupStaticProperties="false">
+  <testsuites>
+    <testsuite name="Seatplus Test Suite">
+      <directory>tests</directory>
+    </testsuite>
+  </testsuites>
+  <logging>
+    <junit outputFile="build/report.junit.xml"/>
+  </logging>
+  <source>
+    <include>
+      <directory suffix=".php">./src</directory>
+    </include>
+  </source>
 </phpunit>

rector.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+use Rector\Config\RectorConfig;
+use Rector\Set\ValueObject\SetList;
+
+return RectorConfig::configure()
+    ->withSets([
+        SetList::PHP_85,
+    ])
+    ->withPaths([
+        __DIR__.'/src',
+        __DIR__.'/tests',
+        __DIR__.'/bin',
+    ]);
+// uncomment to reach your current PHP version
+// ->withPhpSets()

src/CacheMiddleware/CacheMiddlewareInterface.php

@@ -6,5 +6,5 @@
 
 interface CacheMiddlewareInterface
 {
-    public function getCacheMiddleware() : CacheMiddleware;
+    public function getCacheMiddleware(): CacheMiddleware;
 }

src/CacheMiddleware/LaravelFileCacheMiddleware.php

@@ -9,6 +9,7 @@
 
 class LaravelFileCacheMiddleware implements CacheMiddlewareInterface
 {
+    #[\Override]
     public function getCacheMiddleware(): CacheMiddleware
     {
         return new CacheMiddleware(

src/CacheMiddleware/NullCacheMiddleware.php

@@ -7,10 +7,11 @@
 
 class NullCacheMiddleware implements CacheMiddlewareInterface
 {
+    #[\Override]
     public function getCacheMiddleware(): CacheMiddleware
     {
-        return  new CacheMiddleware(
-            new NullCacheStrategy()
+        return new CacheMiddleware(
+            new NullCacheStrategy
         );
     }
 }