@shipload/sdk 2.0.0-rc1 → 2.0.0-rc3

package/README.md

@@ -1 +1,349 @@
-# SDK
+# Shipload SDK
+
+TypeScript SDK for Shipload, a blockchain-based space trading game on Antelope blockchains.
+
+## Installation
+
+```bash
+yarn add @shipload/sdk
+```
+
+## Quick Start
+
+```typescript
+import Shipload from '@shipload/sdk'
+
+// Initialize with chain
+const sdk = await Shipload.load('jungle4')
+
+// Get player data
+const player = await sdk.players.getPlayer('myaccount')
+
+// Get ships
+const ships = await sdk.entities.getShips('myaccount')
+
+// Find profitable trades
+const deals = await sdk.trades.findDeals(ships[0])
+```
+
+## Architecture
+
+### Main Class
+
+`Shipload` is the main entry point providing access to all SDK functionality through lazy-loaded managers.
+
+```typescript
+const sdk = await Shipload.load('jungle4', {
+    platformContractName: 'shipplatform',
+    serverContractName: 'shipserver11',
+})
+
+// Managers
+sdk.entities // Entity retrieval (ships, warehouses, containers)
+sdk.players // Player data
+sdk.locations // Location and market data
+sdk.trades // Trade analysis
+sdk.epochs // Epoch timing
+sdk.actions // Action builders for transactions
+
+// Game state
+const game = await sdk.getGame()
+const state = await sdk.getState()
+```
+
+### Managers
+
+| Manager            | Purpose                                            |
+| ------------------ | -------------------------------------------------- |
+| `EntitiesManager`  | Fetch ships, warehouses, containers by ID or owner |
+| `PlayersManager`   | Get player accounts and financial data             |
+| `LocationsManager` | Market prices, system discovery, nearby planets    |
+| `TradesManager`    | Find profitable trade routes with caching          |
+| `EpochsManager`    | Epoch timing, progress, remaining time             |
+| `ActionsManager`   | Build transaction actions for all game operations  |
+
+### Entities
+
+Entity classes wrap contract data with computed properties and methods:
+
+```typescript
+// Ship - Full-featured movable entity
+const ship = await sdk.entities.getShip(123)
+ship.name // Ship name
+ship.isIdle // No pending tasks
+ship.maxDistance // Max travel range
+ship.availableCapacity // Remaining cargo space
+ship.energyPercent // 0-100 energy level
+ship.needsRecharge // Below capacity
+ship.sellableCargo // Cargo that can be sold
+ship.sched.isComplete(now) // Schedule accessor
+ship.inv.totalMass // Inventory accessor
+
+// Warehouse - Stationary storage
+const warehouse = await sdk.entities.getWarehouse(456)
+warehouse.availableCapacity
+warehouse.orbitalAltitude
+
+// Container - Movable cargo container
+const container = await sdk.entities.getContainer(789)
+container.totalMass
+
+// Player - Account with financial helpers
+const player = await sdk.players.getPlayer('account')
+player.availableLoan
+player.canBuyShip()
+player.getNextShipCost()
+
+// Location - Coordinates with market data
+const location = ship.location
+location.marketPrices // Cached prices
+location.getSupply(goodId) // Available supply
+```
+
+### Capabilities
+
+Type guards for entity feature detection:
+
+```typescript
+import {canMove, hasEnergy, hasStorage, hasExtractor} from '@shipload/sdk'
+
+if (canMove(entity)) {
+    const distance = maxTravelDistance(entity)
+}
+
+if (hasStorage(entity)) {
+    const space = availableCapacity(entity)
+}
+```
+
+## Pure Functions
+
+Game logic is implemented as pure functions for testability and contract parity.
+
+### Market
+
+```typescript
+import {marketPrice, marketPrices, getRarity, getGood, getGoods} from '@shipload/sdk'
+
+// Get price at location
+const price = marketPrice(location, goodId, game.config.seed, state)
+
+// Get all prices at location
+const prices = marketPrices(location, game.config.seed, state)
+
+// Get rarity tier (legendary, epic, rare, uncommon, common, trash)
+const rarity = getRarity(gameSeed, epochSeed, location, goodId)
+
+// Goods definitions
+const good = getGood(1) // Get good by ID
+const goods = getGoods() // All goods
+```
+
+### Travel
+
+```typescript
+import {
+    distanceBetweenCoordinates,
+    estimateTravelTime,
+    calculateFlightTime,
+    calculateRefuelingTime,
+    findNearbyPlanets,
+} from '@shipload/sdk'
+
+// Distance calculation
+const distance = distanceBetweenCoordinates(origin, destination)
+
+// Full travel time estimate
+const estimate = estimateTravelTime(ship, travelMass, distance, {
+    includeRefuel: true,
+    loadMass: 500,
+    unloadMass: 300,
+})
+
+// Find nearby systems
+const planets = findNearbyPlanets(gameSeed, origin, maxDistance)
+```
+
+Contract-parity functions (prefixed `calc_`) mirror C++ exactly:
+
+```typescript
+import {
+    calc_flighttime,
+    calc_rechargetime,
+    calc_energyusage,
+    calc_acceleration,
+    calc_orbital_altitude,
+} from '@shipload/sdk'
+```
+
+### Trading
+
+```typescript
+import {
+    calculateTradeProfit,
+    calculateMaxTradeQuantity,
+    findDealsForShip,
+    analyzeCollectOptions,
+} from '@shipload/sdk'
+
+// Calculate profit
+const profit = calculateTradeProfit(quantity, buyPrice, sellPrice)
+
+// Find profitable routes
+const deals = await sdk.trades.findDeals(ship, origin, {
+    maxDistance: 5000,
+    minProfit: 100,
+})
+
+// Decision support when arriving
+const options = await sdk.trades.getCollectOptions(ship, arrivedAt)
+// Returns: sell-and-trade, sell-and-reposition, travel-to-sell, etc.
+```
+
+### Scheduling
+
+```typescript
+import {
+    isIdle,
+    scheduleProgress,
+    scheduleRemaining,
+    currentTask,
+    currentTaskType,
+} from '@shipload/sdk'
+
+// Check schedule state
+if (isIdle(entity)) {
+    /* no pending tasks */
+}
+
+// Get progress (0-1)
+const progress = scheduleProgress(entity, Date.now())
+
+// Current task
+const task = currentTask(entity, Date.now())
+const taskType = currentTaskType(entity, Date.now())
+```
+
+### Projection
+
+Project entity state forward through scheduled tasks:
+
+```typescript
+import {projectEntity, projectEntityAt} from '@shipload/sdk'
+
+// Project to schedule completion
+const projected = projectEntity(ship)
+
+// Project to specific time
+const futureState = projectEntityAt(ship, futureTimestamp)
+```
+
+## Actions
+
+Build transaction actions for blockchain submission:
+
+```typescript
+const actions = sdk.actions
+
+// Travel
+const travelAction = actions.travel(shipId, destination, recharge)
+const groupAction = actions.grouptravel([entity1, entity2], destination)
+
+// Trading
+const buyAction = actions.buyGoods(entityId, goodId, quantity)
+const sellAction = actions.sellGoods(entityId, goodId, quantity)
+const sellAllAction = actions.sellAllCargo(ship)
+
+// Cargo transfer
+const transferAction = actions.transfer(sourceType, sourceId, destType, destId, goodId, quantity)
+
+// Ship management
+const rechargeAction = actions.recharge(shipId)
+const resolveAction = actions.resolve(entityId)
+const cancelAction = actions.cancel(entityId, count)
+
+// Purchases
+const buyShipAction = actions.buyShip(account, 'Ship Name')
+const buyWarehouseAction = actions.buyWarehouse(account, 'Warehouse', x, y)
+
+// Financial
+const loanAction = actions.takeLoan(account, amount)
+const payAction = actions.payLoan(account, amount)
+
+// Extraction
+const extractAction = actions.extract(shipId)
+```
+
+## Epoch Management
+
+```typescript
+const epochs = sdk.epochs
+
+// Current epoch info
+const current = epochs.getCurrent()
+const height = epochs.getCurrentHeight()
+
+// Timing
+const remaining = epochs.getTimeRemaining() // milliseconds
+const progress = epochs.getProgress() // 0-1
+
+// Planning
+const fitsInEpoch = epochs.fitsInCurrentEpoch(travelDuration)
+```
+
+## Entity Factories
+
+Create entities for testing without blockchain:
+
+```typescript
+import {makeShip, makeWarehouse, makeContainer} from '@shipload/sdk'
+
+const ship = makeShip({
+    entity_id: 1,
+    owner: 'testaccount',
+    // ... minimal required fields
+})
+```
+
+## Types
+
+```typescript
+import type {
+    Entity,
+    ShipEntity,
+    WarehouseEntity,
+    ContainerEntity,
+    AnyEntity,
+    Good,
+    GoodPrice,
+    Coordinates,
+    Deal,
+    CollectOption,
+    ProjectedEntity,
+} from '@shipload/sdk'
+
+// Constants
+import {PRECISION, EntityType, TaskType, LocationType} from '@shipload/sdk'
+```
+
+## Contract Types
+
+Generated types from blockchain ABIs:
+
+```typescript
+import {ServerContract, PlatformContract} from '@shipload/sdk'
+
+type ShipRow = ServerContract.Types.ship_row
+type PlayerRow = ServerContract.Types.player_row
+type StateRow = ServerContract.Types.state_row
+```
+
+## Development
+
+```bash
+make lib      # Build bundles (CJS, ESM, UMD)
+make test     # Run tests
+make check    # ESLint
+make codegen  # Regenerate contract types
+make dev      # Watch mode
+```