feat: update ship schema

.gitignore

@@ -0,0 +1 @@
+.DS_Store

models/Cooldown.json

@@ -0,0 +1,22 @@
+{
+  "type": "object",
+  "description": "A cooldown is a period of time in which a ship cannot perform certain actions.",
+  "properties": {
+    "totalSeconds": {
+      "type": "integer",
+      "description": "The total duration of the cooldown in seconds",
+      "minimum": 0
+    },
+    "remainingSeconds": {
+      "type": "integer",
+      "description": "The remaining duration of the cooldown in seconds",
+      "minimum": 0
+    },
+    "expiresAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "The date and time when the cooldown expires in ISO 8601 format",
+      "minimum": 0
+    }
+  }
+}

models/Ship.json

@@ -0,0 +1,54 @@
+{
+  "description": "A ship",
+  "type": "object",
+  "properties": {
+    "symbol": {
+      "type": "string",
+      "description": "The globally unique identifier of the ship in the following format: `[AGENT_SYMBOL]_[HEX_ID]`",
+      "minLength": 8,
+      "examples": [
+        "FALCON_0A1",
+        "FALCON_00A"
+      ]
+    },
+    "registration": {
+      "$ref": "./ShipRegistration.json"
+    },
+    "nav": {
+      "$ref": "./ShipNav.json"
+    },
+    "crew": {
+      "$ref": "./ShipCrew.json"
+    },
+    "frame": {
+      "$ref": "./ShipFrame.json"
+    },
+    "reactor": {
+      "$ref": "./ShipReactor.json"
+    },
+    "thrusters": {
+      "$ref": "./ShipThrusters.json"
+    },
+    "modules": {
+      "type": "array",
+      "items": {
+        "$ref": "./ShipModule.json"
+      }
+    },
+    "mounts": {
+      "type": "array",
+      "items": {
+        "$ref": "./ShipMount.json"
+      }
+    },
+    "cargo": {
+      "$ref": "./ShipCargo.json"
+    },
+    "fuel": {
+      "$ref": "./ShipFuel.json"
+    }
+  },
+  "required": [
+    "symbol"
+  ]
+}

models/Ship.yaml

@@ -1,161 +0,0 @@
-description: ""
-type: object
-x-examples:
-  example-1:
-    symbol: 2C52AD-1
-    crew: null
-    officers: null
-    frame: FRAME_FRIGATE
-    reactor: REACTOR_FUSION_I
-    engine: ENGINE_ION_DRIVE_II
-    modules:
-      - MODULE_GAS_TANK
-      - MODULE_CARGO_HOLD
-      - MODULE_CARGO_HOLD
-      - MODULE_CREW_QUARTERS
-      - MODULE_ENVOY_QUARTERS
-      - MODULE_JUMP_DRIVE_I
-    mounts:
-      - MOUNT_SENSOR_ARRAY_II
-      - MOUNT_MINING_LASER_II
-      - MOUNT_GAS_SIPHON_II
-    registration:
-      factionSymbol: COMMERCE_REPUBLIC
-      agentSymbol: 2C52AD
-      fee: 0
-      role: COMMAND
-    integrity:
-      frame: 1
-      reactor: 1
-      engine: 1
-    status: DOCKED
-    location: X1-OE-PM
-    cargo:
-      - tradeSymbol: IRON_ORE
-        units: 100
-examples:
-  - symbol: 55B261-1
-    crew: null
-    officers: null
-    fuel: 100
-    frame: FRAME_DRONE
-    reactor: REACTOR_SOLAR_I
-    engine: ENGINE_SOLAR_PROPULSION
-    modules:
-      - MODULE_CARGO_HOLD
-    mounts:
-      - MOUNT_MINING_LASER_I
-    registration:
-      factionSymbol: COMMERCE_REPUBLIC
-      agentSymbol: 55B261
-      fee: 100
-      role: EXCAVATOR
-    integrity:
-      frame: 1
-      reactor: 1
-      engine: 1
-    status: DOCKED
-    location: X1-OE-PM
-    cargo: []
-properties:
-  symbol:
-    type: string
-    minLength: 1
-  frame:
-    type: string
-    minLength: 1
-  reactor:
-    type: string
-    minLength: 1
-  engine:
-    type: string
-    minLength: 1
-  modules:
-    type: array
-    items:
-      type: string
-  mounts:
-    type: array
-    items:
-      type: string
-  registration:
-    type: object
-    required:
-      - factionSymbol
-      - agentSymbol
-      - fee
-      - role
-    properties:
-      factionSymbol:
-        type: string
-        minLength: 1
-      agentSymbol:
-        type: string
-        minLength: 1
-      fee:
-        type: integer
-      role:
-        type: string
-        minLength: 1
-  integrity:
-    type: object
-    required:
-      - frame
-      - reactor
-      - engine
-    properties:
-      frame:
-        type: number
-      reactor:
-        type: number
-      engine:
-        type: number
-  stats:
-    type: object
-    required:
-      - fuelTank
-      - cargoLimit
-      - jumpRange
-    properties:
-      fuelTank:
-        type: integer
-      cargoLimit:
-        type: integer
-      jumpRange:
-        type: integer
-  status:
-    type: string
-    minLength: 1
-  location:
-    type: string
-    minLength: 1
-  cargo:
-    type: array
-    uniqueItems: true
-    minItems: 0
-    items:
-      type: object
-      properties:
-        tradeSymbol:
-          type: string
-          minLength: 1
-        units:
-          type: integer
-      required:
-        - tradeSymbol
-        - units
-  fuel:
-    type: integer
-required:
-  - symbol
-  - frame
-  - reactor
-  - engine
-  - modules
-  - mounts
-  - registration
-  - integrity
-  - status
-  - location
-  - cargo
-  - fuel

models/ShipCargo.json

@@ -0,0 +1,46 @@
+{
+  "type": "object",
+  "properties": {
+    "size": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "inventory": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "symbol": {
+            "type": "string",
+            "examples": [
+              "ORE_COPPER",
+              "MICROPROCESSORS",
+              "FOOD"
+            ]
+          },
+          "name": {
+            "type": "string",
+            "examples": [
+              "Copper Ore",
+              "Microprocessors",
+              "Food"
+            ]
+          },
+          "units": {
+            "type": "integer",
+            "minimum": 1
+          }
+        },
+        "required": [
+          "symbol",
+          "name",
+          "units"
+        ]
+      },
+      "required": [
+        "size",
+        "inventory"
+      ]
+    }
+  }
+}

models/ShipCondition.json

@@ -0,0 +1,6 @@
+{
+  "type": "integer",
+  "description": "Condition is a range of 0 to 100 where 0 is completely worn out and 100 is brand new.",
+  "minimum": 0,
+  "maximum": 100
+}

models/ShipCrew.json

@@ -0,0 +1,46 @@
+{
+  "type": "object",
+  "required": [
+    "count",
+    "min",
+    "max",
+    "rotation",
+    "morale"
+  ],
+  "description": "The ship's crew service and maintain the ship's systems and equipment.",
+  "properties": {
+    "count": {
+      "type": "integer",
+      "description": "The total number of crew members on the ship."
+    },
+    "min": {
+      "type": "integer",
+      "description": "The minimum number of crew members required to maintain the ship."
+    },
+    "max": {
+      "type": "integer",
+      "description": "The maximum number of crew members the ship can support."
+    },
+    "rotation": {
+      "type": "string",
+      "description": "The rotation of crew shifts. Stricter shifts can improve the ship's performance, and more relaxed shifts can improve the crew's morale.",
+      "enum": [
+        "STRICT",
+        "STANDARD",
+        "RELAXED"
+      ],
+      "default": "STANDARD"
+    },
+    "morale": {
+      "type": "integer",
+      "description": "A rough measure of the crew's morale. A higher morale means the crew is happier and more productive. A lower morale means the ship is more prone to accidents.",
+      "minimum": 0,
+      "maximum": 100
+    },
+    "wages": {
+      "type": "integer",
+      "description": "The amount of credits per crew member paid per minute of time travelled between waypoints. Wages are paid when a ship departs from a waypoint.",
+      "minimum": 0
+    }
+  }
+}

models/ShipFrame.json

@@ -0,0 +1,60 @@
+{
+  "type": "object",
+  "description": "The frame of the ship. The frame determines the number of modules and mounting points of the ship, as well as base fuel capacity. As the condition of the frame takes more wear, the ship will become more sluggish and less maneuverable.",
+  "properties": {
+    "symbol": {
+      "type": "string",
+      "enum": [
+        "FRAME_DRONE",
+        "FRAME_INTERCEPTOR",
+        "FRAME_RACER",
+        "FRAME_FIGHTER",
+        "FRAME_FRIGATE",
+        "FRAME_SHUTTLE",
+        "FRAME_EXPLORER",
+        "FRAME_LIGHT_FREIGHTER",
+        "FRAME_HEAVY_FREIGHTER",
+        "FRAME_TRANSPORT",
+        "FRAME_DESTROYER",
+        "FRAME_CRUISER",
+        "FRAME_CARRIER"
+      ]
+    },
+    "name": {
+      "type": "string",
+      "enum": [
+        "Drone",
+        "Interceptor",
+        "Racer",
+        "Fighter",
+        "Frigate",
+        "Shuttle",
+        "Explorer",
+        "Light Freighter",
+        "Heavy Freighter",
+        "Transport",
+        "Destroyer",
+        "Cruiser",
+        "Carrier"
+      ]
+    },
+    "condition": {
+      "$ref": "./ShipCondition.json"
+    },
+    "moduleSlots": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "mountingPoints": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "fuelCapacity": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "requirements": {
+      "$ref": "./ShipRequirements.json"
+    }
+  }
+}

models/ShipFuel.json

@@ -0,0 +1,35 @@
+{
+  "type": "object",
+  "description": "Details of the ship's fuel tanks including how much fuel was consumed during the last transit or action.",
+  "properties": {
+    "amount": {
+      "type": "integer",
+      "description": "The amount of fuel in the ship's tanks.",
+      "minimum": 0
+    },
+    "max": {
+      "type": "integer",
+      "description": "The maximum amount of fuel the ship's tanks can hold.",
+      "minimum": 0
+    },
+    "consumed": {
+      "type": "object",
+      "properties": {
+        "amount": {
+          "type": "integer",
+          "description": "The amount of fuel consumed by the most recent transit or action.",
+          "minimum": 0
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time",
+          "description": "The time at which the fuel was consumed."
+        }
+      },
+      "required": [
+        "amount",
+        "timestamp"
+      ]
+    }
+  }
+}

models/ShipModule.json

@@ -0,0 +1,33 @@
+{
+  "type": "object",
+  "description": "A module can be installed in a ship and provides a set of capabilities such as storage space or quarters for crew.",
+  "properties": {
+    "symbol": {
+      "type": "string",
+      "enum": [
+        "MODULE_FUEL_TANK",
+        "MODULE_CARGO_HOLD",
+        "MODULE_CREW_QUARTERS",
+        "MODULE_ENVOY_QUARTERS",
+        "MODULE_PASSENGER_CABIN",
+        "MODULE_MICRO_REFINERY",
+        "MODULE_JUMP_DRIVE"
+      ]
+    },
+    "name": {
+      "type": "string",
+      "enum": [
+        "Fuel Tank",
+        "Cargo Hold",
+        "Crew Quarters",
+        "Envoy Quarters",
+        "Passenger Cabin",
+        "Micro Refinery",
+        "Jump Drive"
+      ]
+    },
+    "requirements": {
+      "$ref": "./ShipRequirements.json"
+    }
+  }
+}

models/ShipMount.json

@@ -0,0 +1,37 @@
+{
+  "type": "object",
+  "description": "A mount is installed on the exterier of a ship.",
+  "properties": {
+    "symbol": {
+      "type": "string",
+      "enum": [
+        "MOUNT_GAS_SIPHON_I",
+        "MOUNT_GAS_SIPHON_II",
+        "MOUNT_GAS_SIPHON_III",
+        "MOUNT_SENSOR_ARRAY_I",
+        "MOUNT_SENSOR_ARRAY_II",
+        "MOUNT_SENSOR_ARRAY_III",
+        "MOUNT_MINING_LASER_I",
+        "MOUNT_MINING_LASER_II",
+        "MOUNT_MINING_LASER_III"
+      ]
+    },
+    "name": {
+      "type": "string",
+      "enum": [
+        "Gas Siphon I",
+        "Gas Siphon II",
+        "Gas Siphon III",
+        "Sensor Array I",
+        "Sensor Array II",
+        "Sensor Array III",
+        "Mining Laser I",
+        "Mining Laser II",
+        "Mining Laser III"
+      ]
+    },
+    "requirements": {
+      "$ref": "./ShipRequirements.json"
+    }
+  }
+}

models/ShipNav.json

@@ -0,0 +1,20 @@
+{
+  "type": "object",
+  "description": "The navigation information of the ship.",
+  "properties": {
+    "route": {
+      "$ref": "./ShipNavRoute.json"
+    },
+    "status": {
+      "$ref": "./ShipNavStatus.json"
+    },
+    "speed": {
+      "$ref": "./ShipNavSpeed.json"
+    }
+  },
+  "required": [
+    "route",
+    "status",
+    "speed"
+  ]
+}

models/ShipNavRoute.json

@@ -0,0 +1,34 @@
+{
+  "type": "object",
+  "description": "The routing information for the ship's most recent transit or current location.",
+  "properties": {
+    "symbol": {
+      "type": "string",
+      "description": "The unique identifer of the waypoint."
+    },
+    "name": {
+      "type": "string",
+      "description": "The name of the waypoint."
+    },
+    "x": {
+      "type": "integer",
+      "description": "The x coordinate of the waypoint."
+    },
+    "y": {
+      "type": "integer",
+      "description": "The y coordinate of the waypoint."
+    },
+    "arrival": {
+      "type": "string",
+      "format": "date-time",
+      "description": "The date time of the ship's arrival. If the ship is in-transit, this is the expected time of arrival."
+    }
+  },
+  "required": [
+    "symbol",
+    "name",
+    "x",
+    "y",
+    "arrival"
+  ]
+}

models/ShipNavSpeed.json

@@ -0,0 +1,10 @@
+{
+  "type": "string",
+  "description": "The ship's set speed when travelling between waypoints. Nav speed can wear down the ship's engines and lower crew morale but improves travel time.",
+  "enum": [
+    "CONSERVATIVE",
+    "CRUISE",
+    "MAX"
+  ],
+  "default": "CRUISE"
+}

models/ShipNavStatus.json

@@ -0,0 +1,9 @@
+{
+  "type": "string",
+  "description": "The current status of the ship",
+  "enum": [
+    "IN_TRANSIT",
+    "IN_ORBIT",
+    "DOCKED"
+  ]
+}

models/ShipNavigation.yaml

@@ -1,33 +0,0 @@
-description: ""
-type: object
-properties:
-  shipSymbol:
-    type: string
-    minLength: 1
-  departure:
-    type: string
-    minLength: 1
-  destination:
-    type: string
-    minLength: 1
-  durationRemaining:
-    type: integer
-  arrivedAt: {}
-required:
-  - shipSymbol
-  - departure
-  - destination
-  - durationRemaining
-x-examples:
-  example-1:
-    shipSymbol: 3AE434-1
-    departure: X1-OE-PM
-    destination: X1-OE-A005
-    durationRemaining: 2159
-    arrivedAt: null
-examples:
-  - shipSymbol: 3AE434-1
-    departure: X1-OE-PM
-    destination: X1-OE-A005
-    durationRemaining: 2159
-    arrivedAt: null

models/ShipReactor.json

@@ -0,0 +1,39 @@
+{
+  "type": "object",
+  "description": "The reactor of the ship. It is a large, cylindrical structure that is usually located in the center of the ship. The reactor is responsible for powering the ship's systems and weapons.",
+  "properties": {
+    "symbol": {
+      "type": "string",
+      "enum": [
+        "SOLAR_REACTOR",
+        "FUSION_REACTOR",
+        "FISSION_REACTOR",
+        "CHEMICAL_REACTOR",
+        "DARK_MATTER_REACTOR"
+      ]
+    },
+    "name": {
+      "type": "string",
+      "enum": [
+        "Solar Reactor",
+        "Fusion Reactor",
+        "Fission Reactor",
+        "Chemical Reactor",
+        "Dark Matter Reactor"
+      ]
+    },
+    "condition": {
+      "$ref": "./ShipCondition.json"
+    },
+    "powerOutput": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "cooldown": {
+      "$ref": "./Cooldown.json"
+    },
+    "requirements": {
+      "$ref": "./ShipRequirements.json"
+    }
+  }
+}

models/ShipRegistration.json

@@ -0,0 +1,32 @@
+{
+  "type": "object",
+  "required": [
+    "name",
+    "faction",
+    "role"
+  ],
+  "description": "The public registration information of the ship",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The agent's registered name of the ship",
+      "minLength": 1,
+      "examples": [
+        "Red Falcon",
+        "Black Pearl IV",
+        "The Flying Dutchman"
+      ]
+    },
+    "faction": {
+      "type": "string",
+      "description": "The symbol of the faction the ship is registered with",
+      "minLength": 1,
+      "examples": [
+        "F_COMM"
+      ]
+    },
+    "role": {
+      "$ref": "./ShipRole.json"
+    }
+  }
+}

models/ShipRequirements.json

@@ -0,0 +1,18 @@
+{
+  "type": "object",
+  "description": "The requirements for installation on a ship",
+  "properties": {
+    "power": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "crew": {
+      "type": "integer",
+      "minimum": 0
+    }
+  },
+  "required": [
+    "power",
+    "crew"
+  ]
+}

models/ShipRole.json

@@ -0,0 +1,16 @@
+{
+  "type": "string",
+  "description": "The registered role of the ship",
+  "enum": [
+    "FABRICATOR",
+    "HARVESTER",
+    "HAULER",
+    "EXCAVATOR",
+    "TRANSPORT",
+    "REPAIR",
+    "SURVEYOR",
+    "COMMAND",
+    "CARRIER",
+    "PATROL"
+  ]
+}

models/ShipThrusters.json

@@ -0,0 +1,34 @@
+{
+  "type": "object",
+  "description": "The thrusters determine how quickly a ship travels between waypoints.",
+  "properties": {
+    "symbol": {
+      "type": "string",
+      "enum": [
+        "IMPULSE_DRIVE",
+        "ION_DRIVE_I",
+        "ION_DRIVE_II",
+        "HYPER_DRIVE"
+      ]
+    },
+    "name": {
+      "type": "string",
+      "enum": [
+        "Impulse Drive",
+        "Ion Drive",
+        "Advanced Ion Drive",
+        "Hyper Drive"
+      ]
+    },
+    "condition": {
+      "$ref": "./ShipCondition.json"
+    },
+    "speed": {
+      "type": "number",
+      "minimum": 1
+    },
+    "requirements": {
+      "$ref": "./ShipRequirements.json"
+    }
+  }
+}

redocly.yaml

@@ -0,0 +1,18 @@
+# See https://redocly.com/docs/cli/configuration/
+
+apis:
+  # Update the apiName with your actual API name, and the version with your actual API version.
+  SpaceTraders@2.1.0:
+    # Update the path to your OpenAPI root file
+    root: ./reference/SpaceTraders.json
+
+lint:
+  extends:
+    - recommended
+
+features.openapi:
+  generateCodeSamples:
+    languages:
+      - lang: curl
+      - lang: Node.js
+      - lang: Python

resources/agent/MyAgent.json

@@ -0,0 +1,44 @@
+{
+  "get": {
+    "summary": "My Agent Details",
+    "tags": [
+      "agents"
+    ],
+    "responses": {
+      "200": {
+        "description": "OK",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "data": {
+                  "$ref": "../../models/Agent.yaml"
+                }
+              }
+            },
+            "examples": {
+              "Agent": {
+                "value": {
+                  "data": {
+                    "accountId": "cl0hok34m0003ks0jjql5q8f2",
+                    "symbol": "EMBER",
+                    "headquarters": "X1-OE-PM",
+                    "credits": 0
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "operationId": "get-my-agent",
+    "security": [
+      {
+        "AgentToken": []
+      }
+    ],
+    "description": "Fetch your agent's details."
+  }
+}

resources/agent/RegisterAgent.json

@@ -0,0 +1,68 @@
+{
+  "post": {
+    "operationId": "register-agent",
+    "summary": "Register New Agent",
+    "description": "Creates a new agent and ties it to a temporary Account. Use `COMMERCE_REPUBLIC` as your starting faction if you don't know any other factions to choose from.\n\nThe agent symbol is a 4-8 character string that will represent your agent. This symbol will prefix the symbol of every ship you own. Agent symbols will be cast to all uppercase characters.\n\nA new agent will be granted an authorization token, a contract with their starting faction, a command ship with a jump drive, and one hundred thousand credits.\n\n> #### Keep your token safe and secure\n>\n> Save your token during the alpha phase. There is no way to regenerate this token without starting a new agent. In the future you will be able to generate and manage your tokens from the SpaceTraders website.\n\nYou can accept your contract using the `/my/contracts/{contractId}/accept` endpoint. You will want to navigate your command ship to a nearby asteroid field waypoint, and execute the `/my/ships/{shipSymbol}/accept` endpoint to mine various types of ores and minerals.\n\nReturn to the contract destination and execute the `/my/ships/{shipSymbol}/deliver` endpoint to deposit goods into the contract.\n\nWhen your contract is fulfilled, you can call `/my/contracts/{contractId}/fulfill` to retrieve payment.",
+    "requestBody": {
+      "content": {
+        "application/json": {
+          "schema": {
+            "type": "object",
+            "properties": {
+              "symbol": {
+                "type": "string",
+                "description": "How other agents will see your ships and information.",
+                "minLength": 4,
+                "maxLength": 8,
+                "example": "BADGER"
+              },
+              "faction": {
+                "type": "string",
+                "default": "COMMERCE_REPUBLIC",
+                "description": "The faction you choose determines your headquarters."
+              }
+            }
+          }
+        }
+      },
+      "description": ""
+    },
+    "responses": {
+      "201": {
+        "description": "OK",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "data": {
+                  "type": "object",
+                  "properties": {
+                    "token": {
+                      "type": "string"
+                    },
+                    "agent": {
+                      "$ref": "../../models/Agent.yaml"
+                    },
+                    "faction": {
+                      "$ref": "../../models/Faction.yaml"
+                    },
+                    "contract": {
+                      "$ref": "../../models/Contract.yaml"
+                    },
+                    "ship": {
+                      "$ref": "../../models/Ship.json"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "tags": [
+      "agents"
+    ]
+  }
+}