s10s

package module
v1.0.0-alpha.6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 6, 2024 License: MIT Imports: 11 Imported by: 1

README

spacetraders.io Go SDK

GitHub go.mod Go version GoDoc Go Report Card

This is a basic Go client SDK for spacetraders.io.

API Deviations

The API is pretty similiar compared to the published OpenAPI specification.

A few things are different, though:

SystemSymbol and WaypointSymbol

To diffentiate the two, SystemSymbol and WaypointSymbol have been introduced as seperate types and are used by many of the Calls.

AllSystems instead of ListSystems

Currently approximately 8500 systems exist in the game. Instead of a slice of these, a channel is used, so you can use them right away.

GetCargo is missing

Use GetMyShipFromValue instead and profit from all the other infos you also get with one API call.

GetScrapShip

GET https://api.spacetraders.io/v2/my/ships/{shipSymbol}/scrap was renamed to GetScrapShipValue

regenerate client from OpenAPI specification

rm -r openapi
mkdir openapi
openapi-generator generate -g go -i "https://stoplight.io/api/v1/projects/spacetraders/spacetraders/nodes/reference/SpaceTraders.json?fromExportButton=true&snapshotType=http_service&deref=optimizedBundle" --skip-validate-spec -o openapi -c openapi-cfg.json --git-host github.com --git-repo-id s10s --git-user-id ruudiRatlos
gofmt -s -w ./openapi

Release

export TAG=v1.0.x
git tag $TAG
git push origin $TAG
GOPROXY=proxy.golang.org go list -m github.com/ruudiRatlos/s10s@$TAG

Documentation

Index

Constants

View Source
const (
	EvAgentChange                    string = "s10s.agent.change"
	EvConstructionChange             string = "s10s.construction.change"
	EvTransactionNew                 string = "s10s.transaction.new"
	EvExtractionNew                  string = "s10s.extraction.new"
	EvSiphonNew                      string = "s10s.siphon.new"
	EvShipChange                     string = "s10s.ship.change"
	EvShipCondition                  string = "s10s.ship.condition.event.new"
	EvWaypointChange                 string = "s10s.system.waypoint.change"
	EvContractChange                 string = "s10s.contract.change"
	EvSystem                         string = "s10s.system.change"
	EvJumpGate                       string = "s10s.jumpgate.change"
	EvMarket                         string = "s10s.market.success"
	EvShipyard                       string = "s10s.shipyard.change"
	EvShipyardTransactionNew         string = "s10s.shipyard.transaction.new"
	EvShipModificationTransactionNew string = "s10s.ship.transaction.new"
	EvScrapTransactionNew            string = "s10s.ship.scrap.new"
	EvRepairTransactionNew           string = "s10s.ship.repair.new"
)
View Source
const ErrConstructionMaterialFulfilled = 4801
View Source
const ErrConstructionMaterialNotRequired = 4800
View Source
const ErrShipTransferAgentConflict = 4232
View Source
const ErrShipTransferLocationConflict = 4234
View Source
const ErrShipTransferSameShipConflict = 4233
View Source
const ErrShipTransferShipNotFound = 4231

Variables

Functions

func AppendCtx

func AppendCtx(parent context.Context, attrs ...slog.Attr) context.Context

AppendCtx adds an slog attribute to the provided context so that it will be included in any Record created with such context

func CopyAgent

func CopyAgent(from *api.Agent) *api.Agent

CopyAgent creates a new copy of the given agent

func CopyShipState

func CopyShipState(to, from *api.Ship)

CopyShipState changes all public properties of to to the values of from

func GetStatus

func GetStatus() (*api.GetStatus200Response, error)

GetStatus returns the current status

func Register

func Register(faction, name string, email string) (*api.Register201ResponseData, error)

Register registers a new agent

func WithToken

func WithToken(token string) func(*Client) error

func WithTokenFromEnv

func WithTokenFromEnv(c *Client) error

func WithoutLogging

func WithoutLogging(c *Client) error

Types

type APIError

type APIError int
const ErrAcceptContractConflict APIError = 4501
const ErrAcceptContractNotAuthorized APIError = 4500
const ErrAccountHasNoAgent APIError = 4108
const ErrAccountNotExists APIError = 4106
const ErrAgentNotExists APIError = 4107
const ErrContractDeadline APIError = 4503
const ErrContractFulfilled APIError = 4504
const ErrContractNotAccepted APIError = 4505
const ErrContractNotAuthorized APIError = 4506
const ErrCooldownConflict APIError = 4000
const ErrExistingContract APIError = 4511
const ErrFulfillContractDelivery APIError = 4502
const ErrInvalidTokenRequest APIError = 4104
const ErrInvalidTokenSubject APIError = 4105
const ErrMarketNotFound APIError = 4603
const ErrMarketTradeInsufficientCredits APIError = 4600
const ErrMarketTradeNoPurchase APIError = 4601
const ErrMarketTradeNotSold APIError = 4602
const ErrMarketTradeUnitLimit APIError = 4604
const ErrMissingTokenRequest APIError = 4103
const ErrNavigateInTransit APIError = 4200
const ErrNavigateInsufficientFuel APIError = 4203
const ErrNavigateInvalidDestination APIError = 4201
const ErrNavigateOutsideSystem APIError = 4202
const ErrNavigateSameDestination APIError = 4204
const ErrPurchaseShipCredits APIError = 4216
const ErrPurchaseShipNotPresent APIError = 4245
const ErrRegisterAgentConflictSymbol APIError = 4111
const ErrRegisterAgentExists APIError = 4109
const ErrRegisterAgentSymbolReserved APIError = 4110
const ErrShipCargoExceedsLimit APIError = 4217
const ErrShipCargoFull APIError = 4228
const ErrShipCargoMissing APIError = 4218
const ErrShipCargoUnitCount APIError = 4219
const ErrShipConstructionInvalidLocation APIError = 4802
const ErrShipDeliverFulfilled APIError = 4509
const ErrShipDeliverInvalidLocation APIError = 4510
const ErrShipDeliverTerms APIError = 4508
const ErrShipExtractDestabilized APIError = 4253
const ErrShipExtractInvalidWaypoint APIError = 4205
const ErrShipExtractPermission APIError = 4206
const ErrShipInTransit APIError = 4214
const ErrShipInvalidRefineryGood APIError = 4237
const ErrShipInvalidRefineryType APIError = 4238
const ErrShipJumpDestinationUnderConstruction APIError = 4262
const ErrShipJumpFromGateToGate APIError = 4229
const ErrShipJumpInvalidOrigin APIError = 4254
const ErrShipJumpInvalidWaypoint APIError = 4255
const ErrShipJumpMissingAntimatter APIError = 4212
const ErrShipJumpMissingModule APIError = 4210
const ErrShipJumpNoSystem APIError = 4207
const ErrShipJumpNoValidWaypoint APIError = 4211
const ErrShipJumpOriginUnderConstruction APIError = 4256
const ErrShipJumpSameSystem APIError = 4208
const ErrShipMissingCrew APIError = 4252
const ErrShipMissingGasProcessor APIError = 4257
const ErrShipMissingGasSiphons APIError = 4258
const ErrShipMissingMineralProcessor APIError = 4242
const ErrShipMissingMiningLasers APIError = 4243
const ErrShipMissingMount APIError = 4247
const ErrShipMissingMounts APIError = 4227
const ErrShipMissingPower APIError = 4249
const ErrShipMissingRefinery APIError = 4239
const ErrShipMissingSensorArrays APIError = 4215
const ErrShipMissingSlots APIError = 4250
const ErrShipMissingSurveyor APIError = 4240
const ErrShipMissingWarpDrive APIError = 4241
const ErrShipMountInsufficientCredits APIError = 4248
const ErrShipMountNoShipyard APIError = 4246
const ErrShipNotDocked APIError = 4244
const ErrShipNotInOrbit APIError = 4236
const ErrShipRefuelDocked APIError = 4225
const ErrShipRefuelInvalidWaypoint APIError = 4226
const ErrShipSiphonInvalidWaypoint APIError = 4259
const ErrShipSiphonPermission APIError = 4260
const ErrShipSurveyExhausted APIError = 4224
const ErrShipSurveyExpiration APIError = 4221
const ErrShipSurveyOrbit APIError = 4223
const ErrShipSurveyVerification APIError = 4220
const ErrShipSurveyWaypointType APIError = 4222
const ErrTokenEmpty APIError = 4100
const ErrTokenInvalidSubject APIError = 4102
const ErrTokenMissingSubject APIError = 4101
const ErrWarpInsideSystem APIError = 4235
const ErrWaypointCharted APIError = 4230
const ErrWaypointNoAccess APIError = 4001
const ErrWaypointNoFaction APIError = 4700
const ErrWaypointNoYield APIError = 4261

func (APIError) Error

func (e APIError) Error() string

func (APIError) Is

func (e APIError) Is(target error) bool

type AgentsAPI

type AgentsAPI service

func (*AgentsAPI) AllAgents

func (c *AgentsAPI) AllAgents(ctx context.Context) (<-chan *api.Agent, int, error)

AllAgents returns a channel of all agents and the number of agents to be returned

func (*AgentsAPI) GetMyAgent

func (aa *AgentsAPI) GetMyAgent(ctx context.Context) (*api.Agent, error)

GetMyAgent

func (*AgentsAPI) GetPublicAgent

func (aa *AgentsAPI) GetPublicAgent(ctx context.Context, agentSym string) (*api.Agent, error)

GetPublicAgent

type Client

type Client struct {
	AgentsAPI    *AgentsAPI
	SystemsAPI   *SystemsAPI
	FleetAPI     *FleetAPI
	ContractsAPI *ContractsAPI
	FactionsAPI  *FactionsAPI
	// contains filtered or unexported fields
}

Client represents a retrying REST API Client for spacetraders

func NewClient

func NewClient(opts ...ClientOption) (*Client, error)

NewClient creates a new Spacetraders client

func (Client) ContextWithToken

func (bc Client) ContextWithToken(ctx context.Context) context.Context

func (Client) Sleep

func (s Client) Sleep(ctx context.Context, wait time.Duration) error

Sleep for the given duration unless interrupted by a canceled Context

func (Client) SleepUntil

func (s Client) SleepUntil(ctx context.Context, t time.Time) error

func (Client) SleepWithJitter

func (s Client) SleepWithJitter(ctx context.Context, wait time.Duration) error

SleepWithJitter sleeps for at least the given duration and adds a random increment up to 10% of the given duration unless interrupted by a canceled Context

type ClientOption

type ClientOption func(*Client) error

func WithEvents

func WithEvents(em FireEventer) ClientOption

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) ClientOption

func WithLogger

func WithLogger(logger *slog.Logger) ClientOption

type ContextHandler

type ContextHandler struct {
	slog.Handler
}

func NewContextHandler

func NewContextHandler(h slog.Handler) ContextHandler

func (ContextHandler) Handle

func (h ContextHandler) Handle(ctx context.Context, r slog.Record) error

Handle adds contextual attributes to the Record before calling the underlying handler

type ContractsAPI

type ContractsAPI service

func (*ContractsAPI) AcceptContract

func (c *ContractsAPI) AcceptContract(ctx context.Context, contract *api.Contract) (*api.AcceptContract200ResponseData, error)

AcceptContract accepts a contract by ID You can only accept contracts that were offered to you, were not accepted yet, and whose deadlines has not passed yet.

func (*ContractsAPI) DeliverContract

func (c *ContractsAPI) DeliverContract(ctx context.Context, contract *api.Contract, ship *api.Ship, good api.TradeSymbol, units int32) (*api.DeliverContract200ResponseData, error)

DeliverCargo returns data about a contract

func (*ContractsAPI) FulfillContract

func (c *ContractsAPI) FulfillContract(ctx context.Context, contract *api.Contract) (*api.AcceptContract200ResponseData, error)

FulfillContract fulfills a contract. Can only be used on contracts that have all of their delivery terms fulfilled.

func (*ContractsAPI) GetContract

func (c *ContractsAPI) GetContract(ctx context.Context, contractID string) (*api.Contract, error)

GetContract returns data about a contract by ID

func (*ContractsAPI) ListContracts

func (c *ContractsAPI) ListContracts(ctx context.Context) ([]*api.Contract, error)

ListContracts returns a list of all your contracts.

type FactionsAPI

type FactionsAPI service

func (*FactionsAPI) GetFaction

func (c *FactionsAPI) GetFaction(ctx context.Context, factionSymbol string) (*api.Faction, error)

GetFaction returns the details of a faction

func (*FactionsAPI) ListFactions

func (c *FactionsAPI) ListFactions(ctx context.Context) ([]*api.Faction, error)

ListFactions returns a list of all factions in the game.

type FireEventer

type FireEventer interface {
	FireEvent(name string, data map[string]any) error
}

type FleetAPI

type FleetAPI service

func (*FleetAPI) CreateChart

func (c *FleetAPI) CreateChart(ctx context.Context, ship *api.Ship) (*api.CreateChart201ResponseData, error)

CreateChart

func (*FleetAPI) CreateSurvey

func (c *FleetAPI) CreateSurvey(ctx context.Context, ship *api.Ship) (*api.CreateSurvey201ResponseData, error)

CreateSurvey returns new survey data

func (*FleetAPI) DockShip

func (c *FleetAPI) DockShip(ctx context.Context, ship *api.Ship) error

DockShip to a waypoint

func (*FleetAPI) ExtractResources

func (c *FleetAPI) ExtractResources(ctx context.Context, ship *api.Ship) (*api.ExtractResources201ResponseData, error)

ExtractResources

func (*FleetAPI) ExtractResourcesWithSurvey

func (c *FleetAPI) ExtractResourcesWithSurvey(ctx context.Context, ship *api.Ship, survey *api.Survey) (*api.ExtractResources201ResponseData, error)

ExtractResourcesWithSurvey

func (*FleetAPI) GetMounts

func (c *FleetAPI) GetMounts(ctx context.Context, ship *api.Ship) ([]api.ShipMount, error)

GetMounts gets the mounts installed on a ship.

func (*FleetAPI) GetMyShipFromSymbol

func (c *FleetAPI) GetMyShipFromSymbol(ctx context.Context, shipSymbol string) (*api.Ship, error)

GetMyShipFromSymbol returns data about a ship

func (*FleetAPI) GetMyShips

func (c *FleetAPI) GetMyShips(ctx context.Context) ([]*api.Ship, error)

GetMyShips returns a paginated list of all ships under your agent's ownership.

func (*FleetAPI) GetRepairShipCost

func (c *FleetAPI) GetRepairShipCost(ctx context.Context, ship *api.Ship) (*api.RepairTransaction, error)

GetRepairShipCost

func (*FleetAPI) GetScrapShipValue

func (c *FleetAPI) GetScrapShipValue(ctx context.Context, ship *api.Ship) (*api.GetScrapShip200ResponseData, error)

GetScrapShipValue gets the amount of value that will be returned when scrapping a ship. The ship must be docked in a waypoint that has the Shipyard trait in order to use this function.

func (*FleetAPI) GetShipNav

func (c *FleetAPI) GetShipNav(ctx context.Context, ship *api.Ship) error

GetShipNav

func (*FleetAPI) InstallMount

func (c *FleetAPI) InstallMount(ctx context.Context, ship *api.Ship, mountSym string) (*api.InstallMount201ResponseData, error)

InstallMount installs a mount on a ship.

func (*FleetAPI) JettisonCargo

func (c *FleetAPI) JettisonCargo(ctx context.Context, ship *api.Ship, good api.TradeSymbol, units int32) error

Jettison Cargo ejects the given units of TradeSymbol. If units is -1 all units are ejected

func (*FleetAPI) JumpShip

func (c *FleetAPI) JumpShip(ctx context.Context, ship *api.Ship, wp string) (*api.JumpShip200ResponseData, error)

JumpShip

func (*FleetAPI) ListShips

func (c *FleetAPI) ListShips(ctx context.Context) ([]*api.Ship, error)

ListShips is an alias for GetMyShips

func (*FleetAPI) NavigateShip

func (c *FleetAPI) NavigateShip(ctx context.Context, ship *api.Ship, waypoint string) (*api.NavigateShip200ResponseData, error)

NavigateShip to a waypoint

func (*FleetAPI) NegotiateContract

func (c *FleetAPI) NegotiateContract(ctx context.Context, ship *api.Ship) (*api.Contract, error)

NegotiateContract

func (*FleetAPI) OrbitShip

func (c *FleetAPI) OrbitShip(ctx context.Context, ship *api.Ship) error

OrbitShip attempts to move your ship into orbit at its current location. The request will only succeed if your ship is capable of moving into orbit at the time of the request.

func (*FleetAPI) PatchShipNav

func (c *FleetAPI) PatchShipNav(ctx context.Context, ship *api.Ship, fm api.ShipNavFlightMode) error

PatchShipNav

func (*FleetAPI) PurchaseCargo

func (c *FleetAPI) PurchaseCargo(ctx context.Context, ship *api.Ship, good api.TradeSymbol, units int32) (*api.SellCargo201ResponseData, error)

PurchaseCargo buys the given units of TradeSymbol at the local market.

func (*FleetAPI) PurchaseShip

func (c *FleetAPI) PurchaseShip(ctx context.Context,
	shipType api.ShipType, wpSym WaypointSymbol) (*api.PurchaseShip201ResponseData, error)

Purchase a ship

func (*FleetAPI) RefuelShip

func (c *FleetAPI) RefuelShip(ctx context.Context, ship *api.Ship, fromCargo bool, units int32) (*api.RefuelShip200ResponseData, error)

Refuels a ship. If fromCargo is false, fuel is bought from the local market. If units<0, ship is refueled to the maximum.

func (*FleetAPI) RemoveMount

func (c *FleetAPI) RemoveMount(ctx context.Context, ship *api.Ship, mountSym string) (*api.RemoveMount201ResponseData, error)

RemoveMount removes a mount from a ship.

func (*FleetAPI) RepairShip

func (c *FleetAPI) RepairShip(ctx context.Context, ship *api.Ship) (*api.RepairShip200ResponseData, error)

RepairShip

func (*FleetAPI) ScanShips

Scan Ships

func (*FleetAPI) ScanSystems

Scan Systems

func (*FleetAPI) ScanWaypoints

Scan Waypoints

func (*FleetAPI) ScrapShip

func (c *FleetAPI) ScrapShip(ctx context.Context, ship *api.Ship) (*api.ScrapShip200ResponseData, error)

ScrapShip removes a ship from the game The ship must be docked in a waypoint that has the Shipyard trait in order to use this function.

func (*FleetAPI) SellCargo

func (c *FleetAPI) SellCargo(ctx context.Context, ship *api.Ship, good api.TradeSymbol, units int32) (*api.SellCargo201ResponseData, error)

SellCargo sells the given units of TradeSymbol at the local market. If units is -1 all units are sold

func (*FleetAPI) ShipRefine

func (c *FleetAPI) ShipRefine(ctx context.Context, ship *api.Ship, produce api.TradeSymbol) (*api.ShipRefine201ResponseData, error)

ShipRefine

func (*FleetAPI) SiphonResources

func (c *FleetAPI) SiphonResources(ctx context.Context, ship *api.Ship) (*api.SiphonResources201ResponseData, error)

SiphonResources

func (*FleetAPI) TransferCargo

func (c *FleetAPI) TransferCargo(ctx context.Context, target, source *api.Ship, good api.TradeSymbol, units int32) error

Transfer Cargo transfer the given units of TradeSymbol from source to to target. If units is -1 all units are transferred.

func (*FleetAPI) UpdateCooldown

func (c *FleetAPI) UpdateCooldown(ctx context.Context, ship *api.Ship) error

UpdateCooldown returns cooldown data

func (*FleetAPI) WarpShip

func (c *FleetAPI) WarpShip(ctx context.Context, ship *api.Ship, wpSym WaypointSymbol) (*api.WarpShip200ResponseData, error)

WarpShip

type HTTPStatusError

type HTTPStatusError int
const ErrHTTPStatus409 HTTPStatusError = 409
const ErrHTTPStatus429 HTTPStatusError = 429

func (HTTPStatusError) Error

func (e HTTPStatusError) Error() string

func (HTTPStatusError) Is

func (e HTTPStatusError) Is(target error) bool

type Locationeers

type Locationeers interface {
	*api.Construction | *api.Waypoint | *api.Shipyard | *api.Agent | *api.JumpGate | *api.Ship | *api.Survey | *api.Market
	GetSymbol() string
}

type SysLocationeers

type SysLocationeers interface {
	*api.System | *api.Construction | *api.Waypoint | *api.Shipyard | *api.Agent | *api.JumpGate | *api.Ship
	GetSymbol() string
}

type SystemSymbol

type SystemSymbol string

SystemSymbol identifies a system, containing one dash

func SystemSymbolFrom

func SystemSymbolFrom[T SysLocationeers](v T) SystemSymbol

func SystemSymbolFromValue

func SystemSymbolFromValue(sys string) SystemSymbol

func (SystemSymbol) Equals

func (sys SystemSymbol) Equals(sys2 SystemSymbol) bool

func (SystemSymbol) String

func (sys SystemSymbol) String() string

type SystemsAPI

type SystemsAPI service

func (*SystemsAPI) AllSystems

func (c *SystemsAPI) AllSystems(ctx context.Context) (<-chan *api.System, int, error)

AllSystems returns a channel of all systems and the number of systems to be returned

func (*SystemsAPI) GetConstruction

func (c *SystemsAPI) GetConstruction(ctx context.Context, wp *api.Waypoint) (*api.Construction, error)

GetConstruction gets construction details for a waypoint. Requires a waypoint with a property of isUnderConstruction to be true.

func (*SystemsAPI) GetJumpGate

func (c *SystemsAPI) GetJumpGate(ctx context.Context, wpSym WaypointSymbol) (*api.JumpGate, error)

GetJumpGate gets jump gate details for a waypoint. Requires a waypoint of type JUMP_GATE to use.

func (*SystemsAPI) GetMarket

func (c *SystemsAPI) GetMarket(ctx context.Context, wpSym WaypointSymbol) (*api.Market, error)

GetMarket retrieve imports, exports and exchange data from a marketplace. Requires a waypoint that has the Marketplace trait to use.

Send a ship to the waypoint to access trade good prices and recent transactions.

func (*SystemsAPI) GetShipyard

func (c *SystemsAPI) GetShipyard(ctx context.Context, wpSym WaypointSymbol) (*api.Shipyard, error)

GetShipyard gets the shipyard for a waypoint. Requires a waypoint that has the Shipyard trait to use.

Send a ship to the waypoint to access data on ships that are currently available for purchase and recent transactions.

func (*SystemsAPI) GetSystem

func (c *SystemsAPI) GetSystem(ctx context.Context, sys SystemSymbol) (*api.System, error)

GetSystem returns the details of a system

func (*SystemsAPI) GetSystemWaypoints

func (c *SystemsAPI) GetSystemWaypoints(ctx context.Context, sys SystemSymbol) ([]*api.Waypoint, error)

func (*SystemsAPI) GetWaypoint

func (c *SystemsAPI) GetWaypoint(ctx context.Context, wpSym WaypointSymbol) (*api.Waypoint, error)

GetWaypoint

func (*SystemsAPI) SupplyConstruction

func (c *SystemsAPI) SupplyConstruction(ctx context.Context, ship *api.Ship, good *api.TradeSymbol, units int32) (*api.SupplyConstruction201ResponseData, error)

SupplyConstruction supply a construction site with the specified good. Requires a waypoint with a property of isUnderConstruction to be true.

The good must be in your ship's cargo. The good will be removed from your ship's cargo and added to the construction site's materials.

type WaypointSymbol

type WaypointSymbol string

WaypointSymbol identifies a waypoint with a specific system, prefixed with their respective SystemSymbol

func MustWaypointSymbolFromValue

func MustWaypointSymbolFromValue(wp string) WaypointSymbol

func WaypointSymbolFrom

func WaypointSymbolFrom[T Locationeers](v T) WaypointSymbol

func WaypointSymbolFromValue

func WaypointSymbolFromValue(wp string) (WaypointSymbol, error)

func (WaypointSymbol) Equals

func (wp WaypointSymbol) Equals(wp2 WaypointSymbol) bool

func (WaypointSymbol) String

func (wp WaypointSymbol) String() string

func (WaypointSymbol) SystemSymbol

func (wp WaypointSymbol) SystemSymbol() SystemSymbol

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL