@shipload/sdk 2.0.0-rc6 → 2.0.0-rc7

package/README.md

@@ -1,349 +1 @@
-# 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
-```
+# SDK