✨feature: Initial info gathering
This commit is contained in:
Keith Solomon
465
lib/spacetraders-api.php
Normal file
465
lib/spacetraders-api.php
Normal file
@@ -0,0 +1,465 @@
|
||||
<?php
|
||||
/**
|
||||
* Spacetraders API Client Library
|
||||
*
|
||||
* This library provides a simple interface to interact with the Spacetraders API,
|
||||
* allowing you to manage your agents, ships, and other resources in the game.
|
||||
* It includes methods for authentication, making API requests, and handling responses,
|
||||
* making it easier to integrate Spacetraders into your applications or scripts.
|
||||
*
|
||||
* @package SpacetradersAPI
|
||||
* @author Keith Solomon <keith@keithsolomon.net>
|
||||
* @license MIT License
|
||||
* @version GIT: <git_id>
|
||||
* @link https://spacetraders.io
|
||||
*/
|
||||
|
||||
require_once __DIR__ . '/spacetraders-api-exception.php';
|
||||
require_once __DIR__ . '/spacetraders-storage.php';
|
||||
|
||||
/**
|
||||
* Spacetraders API Client
|
||||
*
|
||||
* Main client class for interacting with the Spacetraders API. Provides methods
|
||||
* for authentication, managing agents, ships, contracts, systems, and performing
|
||||
* various game actions like navigation, trading, and resource extraction.
|
||||
*
|
||||
* @package SpacetradersAPI
|
||||
*/
|
||||
class SpacetradersApi {
|
||||
/**
|
||||
* The base URL for the Spacetraders API.
|
||||
*
|
||||
* @var string
|
||||
*/
|
||||
private string $baseUrl;
|
||||
|
||||
/**
|
||||
* The authentication token for API requests.
|
||||
*
|
||||
* @var string|null
|
||||
*/
|
||||
private ?string $token;
|
||||
|
||||
/**
|
||||
* The timeout for HTTP requests in seconds.
|
||||
*
|
||||
* @var int
|
||||
*/
|
||||
private int $timeout;
|
||||
/**
|
||||
* Optional SQLite storage for settings and cache.
|
||||
*
|
||||
* @var SpacetradersStorage|null
|
||||
*/
|
||||
private ?SpacetradersStorage $storage;
|
||||
|
||||
/**
|
||||
* Default cache lifetime in seconds.
|
||||
*
|
||||
* @var int
|
||||
*/
|
||||
private int $cacheTtl;
|
||||
|
||||
/**
|
||||
* Constructor for SpacetradersApi.
|
||||
*
|
||||
* @param string|null $token The authentication token for API requests ( default: null ).
|
||||
* @param string $baseUrl The base URL for the Spacetraders API ( default: 'https://api.spacetraders.io/v2' ).
|
||||
* @param int $timeout The timeout for HTTP requests in seconds ( default: 30 ).
|
||||
* @param SpacetradersStorage|null $storage Optional SQLite storage object for settings and caching.
|
||||
* @param int $cacheTtl API cache lifetime in seconds (default: 600).
|
||||
*/
|
||||
public function __construct(
|
||||
?string $token = null,
|
||||
string $baseUrl = 'https://api.spacetraders.io/v2',
|
||||
int $timeout = 30,
|
||||
?SpacetradersStorage $storage = null,
|
||||
int $cacheTtl = 600
|
||||
) {
|
||||
$this->baseUrl = rtrim( $baseUrl, '/' );
|
||||
$this->token = $token;
|
||||
$this->timeout = $timeout;
|
||||
$this->storage = $storage;
|
||||
$this->cacheTtl = max( 1, $cacheTtl );
|
||||
}
|
||||
|
||||
/**
|
||||
* Set the authentication token for API requests.
|
||||
*
|
||||
* @param string $token The authentication token to set.
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function setToken( string $token ): void {
|
||||
$this->token = trim( $token );
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the current authentication token.
|
||||
*
|
||||
* @return string|null The authentication token or null if not set.
|
||||
*/
|
||||
public function getToken(): ?string {
|
||||
return $this->token;
|
||||
}
|
||||
|
||||
/**
|
||||
* Attach storage for API caching and persisted settings.
|
||||
*
|
||||
* @param SpacetradersStorage|null $storage Storage handler.
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function setStorage( ?SpacetradersStorage $storage ): void {
|
||||
$this->storage = $storage;
|
||||
}
|
||||
|
||||
/**
|
||||
* Set cache lifetime for cached API calls in seconds.
|
||||
*
|
||||
* @param int $cacheTtl Cache lifetime in seconds.
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function setCacheTtl( int $cacheTtl ): void {
|
||||
$this->cacheTtl = max( 1, $cacheTtl );
|
||||
}
|
||||
|
||||
/**
|
||||
* Make an HTTP request to the Spacetraders API.
|
||||
*
|
||||
* @param string $method The HTTP method (GET, POST, etc.).
|
||||
* @param string $endpoint The API endpoint to call.
|
||||
* @param array<string,mixed> $payload The request payload data.
|
||||
* @param array<string,mixed> $query The query parameters.
|
||||
*
|
||||
* @return array<string,mixed>
|
||||
* @throws SpacetradersApiException When cURL fails to initialize, JSON encoding fails, network errors occur, or API returns an error response.
|
||||
*/
|
||||
public function request(
|
||||
string $method,
|
||||
string $endpoint,
|
||||
array $payload = array(),
|
||||
array $query = array()
|
||||
): array {
|
||||
$url = $this->_buildUrl( $endpoint, $query );
|
||||
$method = strtoupper( $method );
|
||||
$cacheKey = $this->_buildCacheKey( $method, $url, $payload );
|
||||
|
||||
if ($method === 'GET' && $this->storage !== null ) {
|
||||
$cachedResponse = $this->storage->getCache( $cacheKey );
|
||||
if (is_array( $cachedResponse ) ) {
|
||||
return $cachedResponse;
|
||||
}
|
||||
}
|
||||
|
||||
$ch = curl_init( $url );
|
||||
|
||||
if ($ch === false ) {
|
||||
throw new SpacetradersApiException( 'Unable to initialize cURL.' );
|
||||
}
|
||||
|
||||
$headers = array( 'Accept: application/json' );
|
||||
$jsonPayload = null;
|
||||
|
||||
if (! empty( $this->token ) ) {
|
||||
$headers[] = 'Authorization: Bearer ' . $this->token;
|
||||
}
|
||||
|
||||
if (! empty( $payload ) ) {
|
||||
$jsonPayload = json_encode( $payload );
|
||||
if ($jsonPayload === false ) {
|
||||
throw new SpacetradersApiException( 'Unable to encode request payload as JSON.' );
|
||||
}
|
||||
|
||||
$headers[] = 'Content-Type: application/json';
|
||||
}
|
||||
|
||||
curl_setopt_array(
|
||||
$ch,
|
||||
array(
|
||||
CURLOPT_RETURNTRANSFER => true,
|
||||
CURLOPT_CUSTOMREQUEST => $method,
|
||||
CURLOPT_HTTPHEADER => $headers,
|
||||
CURLOPT_TIMEOUT => $this->timeout,
|
||||
)
|
||||
);
|
||||
|
||||
if ($jsonPayload !== null ) {
|
||||
curl_setopt( $ch, CURLOPT_POSTFIELDS, $jsonPayload );
|
||||
}
|
||||
|
||||
$rawResponse = curl_exec( $ch );
|
||||
|
||||
if ($rawResponse === false ) {
|
||||
$error = curl_error( $ch );
|
||||
curl_close( $ch );
|
||||
throw new SpacetradersApiException( 'Network error: ' . $error );
|
||||
}
|
||||
|
||||
$statusCode = (int) curl_getinfo( $ch, CURLINFO_HTTP_CODE );
|
||||
curl_close( $ch );
|
||||
|
||||
$decoded = json_decode( $rawResponse, true );
|
||||
if (! is_array( $decoded ) ) {
|
||||
throw new SpacetradersApiException(
|
||||
'API returned an invalid JSON response.',
|
||||
$statusCode
|
||||
);
|
||||
}
|
||||
|
||||
if ($statusCode >= 400 ) {
|
||||
$message = $decoded['error']['message'] ?? 'Unknown API error.';
|
||||
$errorCode = (int) ( $decoded['error']['code'] ?? $statusCode );
|
||||
throw new SpacetradersApiException( $message, $errorCode, $decoded );
|
||||
}
|
||||
|
||||
if ($method === 'GET' && $this->storage !== null ) {
|
||||
$this->storage->setCache( $cacheKey, $decoded, $this->cacheTtl );
|
||||
$this->storage->purgeExpiredCache();
|
||||
}
|
||||
|
||||
return $decoded;
|
||||
}
|
||||
|
||||
/**
|
||||
* Register a new agent and returns the API response.
|
||||
*
|
||||
* @param array<string,mixed> $options Optional registration options: `symbol`, `faction`, and `email`.
|
||||
*
|
||||
* @return array<string,mixed>
|
||||
*/
|
||||
public function registerAgent( array $options ): array {
|
||||
return $this->request( 'POST', '/register', $options );
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the current agent's information.
|
||||
*
|
||||
* @return array<string,mixed>
|
||||
*/
|
||||
public function getMyAgent(): array {
|
||||
return $this->request( 'GET', '/my/agent' );
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a list of all ships owned by the current agent.
|
||||
*
|
||||
* @param array<string,mixed> $query
|
||||
*
|
||||
* @return array<string,mixed>
|
||||
*/
|
||||
public function listMyShips( array $query = array() ): array {
|
||||
return $this->request( 'GET', '/my/ships', array(), $query );
|
||||
}
|
||||
|
||||
/**
|
||||
* Get information about a specific ship owned by the current agent.
|
||||
*
|
||||
* @param string $shipSymbol The symbol of the ship to retrieve.
|
||||
*
|
||||
* @return array<string,mixed>
|
||||
*/
|
||||
public function getShip( string $shipSymbol ): array {
|
||||
return $this->request( 'GET', '/my/ships/' . rawurlencode( $shipSymbol ) );
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a list of all contracts for the current agent.
|
||||
*
|
||||
* @param array<string,mixed> $query
|
||||
*
|
||||
* @return array<string,mixed>
|
||||
*/
|
||||
public function listMyContracts( array $query = array() ): array {
|
||||
return $this->request( 'GET', '/my/contracts', array(), $query );
|
||||
}
|
||||
|
||||
/**
|
||||
* Accept a contract for the current agent.
|
||||
*
|
||||
* @param string $contractId The ID of the contract to accept.
|
||||
*
|
||||
* @return array<string,mixed>
|
||||
*/
|
||||
public function acceptContract( string $contractId ): array {
|
||||
return $this->request(
|
||||
'POST',
|
||||
'/my/contracts/' . rawurlencode( $contractId ) . '/accept'
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a list of all systems in the universe.
|
||||
*
|
||||
* @param array<string,mixed> $query
|
||||
*
|
||||
* @return array<string,mixed>
|
||||
*/
|
||||
public function listSystems( array $query = array() ): array {
|
||||
return $this->request( 'GET', '/systems', array(), $query );
|
||||
}
|
||||
|
||||
/**
|
||||
* Get information about a specific system.
|
||||
*
|
||||
* @param string $systemSymbol The symbol of the system to retrieve.
|
||||
*
|
||||
* @return array<string,mixed>
|
||||
*/
|
||||
public function getSystem( string $systemSymbol ): array {
|
||||
return $this->request( 'GET', '/systems/' . rawurlencode( $systemSymbol ) );
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a list of waypoints in a specific system.
|
||||
*
|
||||
* @param string $systemSymbol The symbol of the system to retrieve waypoints from.
|
||||
* @param array<string,mixed> $query
|
||||
*
|
||||
* @return array<string,mixed>
|
||||
*/
|
||||
public function listWaypoints( string $systemSymbol, array $query = array() ): array {
|
||||
return $this->request(
|
||||
'GET',
|
||||
'/systems/' . rawurlencode( $systemSymbol ) . '/waypoints',
|
||||
array(),
|
||||
$query
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Navigate a ship to a specific waypoint.
|
||||
*
|
||||
* @param string $shipSymbol The symbol of the ship to navigate.
|
||||
* @param string $waypointSymbol The symbol of the waypoint to navigate to.
|
||||
*
|
||||
* @return array<string,mixed>
|
||||
*/
|
||||
public function navigateShip( string $shipSymbol, string $waypointSymbol ): array {
|
||||
return $this->request(
|
||||
'POST',
|
||||
'/my/ships/' . rawurlencode( $shipSymbol ) . '/navigate',
|
||||
array( 'waypointSymbol' => $waypointSymbol )
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Put a ship into orbit around its current waypoint.
|
||||
*
|
||||
* @param string $shipSymbol The symbol of the ship to put into orbit.
|
||||
*
|
||||
* @return array<string,mixed>
|
||||
*/
|
||||
public function orbitShip( string $shipSymbol ): array {
|
||||
return $this->request(
|
||||
'POST',
|
||||
'/my/ships/' . rawurlencode( $shipSymbol ) . '/orbit'
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Dock a ship at its current waypoint.
|
||||
*
|
||||
* @param string $shipSymbol The symbol of the ship to dock.
|
||||
*
|
||||
* @return array<string,mixed>
|
||||
*/
|
||||
public function dockShip( string $shipSymbol ): array {
|
||||
return $this->request(
|
||||
'POST',
|
||||
'/my/ships/' . rawurlencode( $shipSymbol ) . '/dock'
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract resources from the current waypoint using the specified ship.
|
||||
*
|
||||
* @param string $shipSymbol The symbol of the ship to use for resource extraction.
|
||||
*
|
||||
* @return array<string,mixed>
|
||||
*/
|
||||
public function extractResources( string $shipSymbol ): array {
|
||||
return $this->request(
|
||||
'POST',
|
||||
'/my/ships/' . rawurlencode( $shipSymbol ) . '/extract'
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Purchase cargo for a specific ship at its current waypoint.
|
||||
*
|
||||
* @param string $shipSymbol The symbol of the ship to purchase cargo for.
|
||||
* @param string $tradeSymbol The symbol of the trade good to purchase.
|
||||
* @param int $units The number of units to purchase.
|
||||
*
|
||||
* @return array<string,mixed>
|
||||
*/
|
||||
public function purchaseCargo( string $shipSymbol, string $tradeSymbol, int $units ): array {
|
||||
return $this->request(
|
||||
'POST',
|
||||
'/my/ships/' . rawurlencode( $shipSymbol ) . '/purchase',
|
||||
array(
|
||||
'symbol' => $tradeSymbol,
|
||||
'units' => $units,
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Sell cargo from a specific ship at its current waypoint.
|
||||
*
|
||||
* @param string $shipSymbol The symbol of the ship to sell cargo from.
|
||||
* @param string $tradeSymbol The symbol of the trade good to sell.
|
||||
* @param int $units The number of units to sell.
|
||||
*
|
||||
* @return array<string,mixed>
|
||||
*/
|
||||
public function sellCargo( string $shipSymbol, string $tradeSymbol, int $units ): array {
|
||||
return $this->request(
|
||||
'POST',
|
||||
'/my/ships/' . rawurlencode( $shipSymbol ) . '/sell',
|
||||
array(
|
||||
'symbol' => $tradeSymbol,
|
||||
'units' => $units,
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Build the full URL for an API endpoint with optional query parameters.
|
||||
*
|
||||
* @param string $endpoint The API endpoint path.
|
||||
* @param array<string,mixed> $query The query parameters to append.
|
||||
*
|
||||
* @return string The complete URL.
|
||||
*/
|
||||
private function _buildUrl( string $endpoint, array $query = array() ): string {
|
||||
$url = $this->baseUrl . '/' . ltrim( $endpoint, '/' );
|
||||
|
||||
if (! empty( $query ) ) {
|
||||
$url .= '?' . http_build_query( $query );
|
||||
}
|
||||
|
||||
return $url;
|
||||
}
|
||||
|
||||
/**
|
||||
* Build a deterministic cache key for an API request.
|
||||
*
|
||||
* @param string $method HTTP method.
|
||||
* @param string $url Full URL.
|
||||
* @param array<string,mixed> $payload Request payload.
|
||||
*
|
||||
* @return string
|
||||
*/
|
||||
private function _buildCacheKey( string $method, string $url, array $payload ): string {
|
||||
$payloadJson = json_encode( $payload );
|
||||
if ($payloadJson === false ) {
|
||||
$payloadJson = '';
|
||||
}
|
||||
|
||||
return hash( 'sha256', $method . '|' . $url . '|' . $payloadJson );
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user