@kayahr/edsm 1.1.0

package/src/main/api/system.ts

@@ -0,0 +1,361 @@
+/*
+ * Copyright (C) 2020 Klaus Reimer <k@ailis.de>
+ * See LICENSE.md for licensing information.
+ */
+
+import type { SystemBody } from "../bodies.ts";
+import type { Id64 } from "../common.ts";
+import type { Commodity, Outfitting, Ship, SystemStation } from "../stations.ts";
+import { NotFoundException } from "../util.ts";
+import { type SystemIdRequestOptions, request } from "./common.ts";
+
+export interface BodyScanValue {
+    bodyId: number;
+    bodyName: string;
+    distance: number;
+    valueMax: number;
+}
+
+/**
+ * Response structure of the EDSM system bodies request.
+ */
+export interface SystemBodiesResponse {
+    id: number;
+    id64: Id64;
+    name: string;
+    url: string;
+    bodies: SystemBody[];
+    bodyCount: number;
+}
+
+/**
+ * Response structure of the EDSM system estimated value request.
+ */
+export interface SystemEstimatedValueResponse {
+    id: number;
+    id64: Id64;
+    name: string;
+    url: string;
+    estimatedValue: number;
+    estimatedValueMapped: number;
+    valuableBodies: BodyScanValue[];
+}
+
+/**
+ * Response structure of the EDSM system stations request.
+ */
+export interface SystemStationsResponse {
+    id: number;
+    id64: Id64;
+    name: string;
+    url: string;
+    stations: SystemStation[];
+}
+
+/**
+ * Response structure of the EDSM system stations market request.
+ */
+export interface StationMarketResponse {
+    id: number;
+    id64: Id64;
+    name: string;
+    marketId: number;
+    sId: number;
+    sName: string;
+    url: string;
+    commodities: Commodity[];
+}
+
+/**
+ * Response structure of the EDSM system stations shipyard request.
+ */
+export interface StationShipyardResponse {
+    id: number;
+    id64: Id64;
+    name: string;
+    marketId: number;
+    sId: number;
+    sName: string;
+    url: string;
+    ships: Ship[];
+}
+
+/**
+ * Response structure of the EDSM system stations outfitting request.
+ */
+export interface StationOutfittingResponse {
+    id: number;
+    id64: Id64;
+    name: string;
+    marketId: number;
+    sId: number;
+    sName: string;
+    url: string;
+    outfitting: Outfitting[];
+}
+
+/**
+ * Returns the system bodies of the given star system.
+ *
+ * @param systemName - The system name.
+ * @param ids        - Optional system IDs if you seek for a duplicate system and want to force a specific ID.
+ * @returns The bodies found on EDSM.
+ * @throws NotFoundException - When system was not found.
+ */
+export async function getSystemBodies(systemName: string, ids?: { systemId?: number, systemId64?: Id64 }): Promise<SystemBodiesResponse> {
+    const response = await request<SystemBodiesResponse>("api-system-v1/bodies", { systemName, ...ids });
+    if (response == null) {
+        throw new NotFoundException(`System not found: ${systemName}`);
+    }
+    return response;
+}
+
+/**
+ * Returns the estimated scan values of a system.
+ *
+ * @param systemName - The system name.
+ * @param ids        - Optional parameters.
+ * @returns The scan values.
+ * @throws NotFoundException - When system was not found.
+ */
+export async function getSystemEstimatedValue(systemName: string, ids?: SystemIdRequestOptions): Promise<SystemEstimatedValueResponse> {
+    const response = await request<SystemEstimatedValueResponse>("api-system-v1/estimated-value", { systemName, ...ids });
+    if (response == null) {
+        throw new NotFoundException(`System not found: ${systemName}`);
+    }
+    return response;
+}
+
+/**
+ * Returns information about stations in a system.
+ *
+ * @param systemName - The system name.
+ * @param ids        - Optional parameters.
+ * @returns The information about stations in a system.
+ * @throws NotFoundException - When system was not found.
+ */
+export async function getSystemStations(systemName: string, ids?: SystemIdRequestOptions): Promise<SystemStationsResponse> {
+    const response = await request<SystemStationsResponse>("api-system-v1/stations", { systemName, ...ids });
+    if (response == null) {
+        throw new NotFoundException(`System not found: ${systemName}`);
+    }
+    return response;
+}
+
+async function getStationDetails<T>(detail: string, marketIdOrSystemName: number | string, stationName?: string, params?: SystemIdRequestOptions): Promise<T> {
+    const url = `api-system-v1/stations/${detail}`;
+    let data: T | null;
+    if (stationName == null) {
+        const marketId = marketIdOrSystemName;
+        data = await request<T>(url, { marketId });
+        if (data == null) {
+            throw new NotFoundException(`Market not found: ${marketId}`);
+        }
+    } else {
+        const systemName = marketIdOrSystemName;
+        data = await request<T>(url, { systemName, stationName, ...params });
+        if (data == null) {
+            throw new NotFoundException(`Station '${stationName}' in '${systemName}' not found`);
+        }
+    }
+    return data;
+}
+
+/**
+ * Returns information about market in a station.
+ *
+ * @param marketId - The market ID.
+ * @returns The information about market in given station.
+ * @throws NotFoundException - When market was not found.
+ */
+export async function getStationMarket(marketId: number): Promise<StationMarketResponse>;
+
+/**
+ * Returns information about market in a station.
+ *
+ * @param systemName  - The system name.
+ * @param stationName - The station name.
+ * @param params      - Optional parameters.
+ * @returns The information about market in given station.
+ * @throws NotFoundException - When market was not found.
+ */
+export async function getStationMarket(systemName: string, stationName: string, params?: SystemIdRequestOptions): Promise<StationMarketResponse>;
+
+export async function getStationMarket(marketIdOrSystemName: number | string, stationName?: string, params?: SystemIdRequestOptions):
+        Promise<StationMarketResponse> {
+    return getStationDetails<StationMarketResponse>("market", marketIdOrSystemName, stationName, params);
+}
+
+/**
+ * Returns information about shipyard in a station.
+ *
+ * @param marketId - The market ID.
+ * @returns The information about shipyard in given station.
+ * @throws NotFoundException - When shipyard was not found.
+ */
+export async function getStationShipyard(marketId: number): Promise<StationShipyardResponse>;
+
+/**
+ * Returns information about shipyard in a station.
+ *
+ * @param systemName  - The system name.
+ * @param stationName - The station name.
+ * @param params      - Optional parameters.
+ * @returns The information about shipyard in given station.
+ * @throws NotFoundException - When shipyard was not found.
+ */
+export async function getStationShipyard(systemName: string, stationName: string, params?: SystemIdRequestOptions): Promise<StationShipyardResponse>;
+
+export async function getStationShipyard(marketIdOrSystemName: number | string, stationName?: string, params?: SystemIdRequestOptions):
+        Promise<StationShipyardResponse> {
+    return getStationDetails<StationShipyardResponse>("shipyard", marketIdOrSystemName, stationName, params);
+}
+
+/**
+ * Returns information about outfitting in a station.
+ *
+ * @param marketId - The market ID.
+ * @returns The information about outfitting in given station.
+ * @throws NotFoundException - When station was not found.
+ */
+export async function getStationOutfitting(marketId: number): Promise<StationOutfittingResponse>;
+
+/**
+ * Returns information about outfitting in a station.
+ *
+ * @param systemName  - The system name.
+ * @param stationName - The station name.
+ * @param params      - Optional parameters.
+ * @returns The information about outfitting in given station.
+ * @throws NotFoundException - When station was not found.
+ */
+export async function getStationOutfitting(systemName: string, stationName: string, params?: SystemIdRequestOptions): Promise<StationOutfittingResponse>;
+
+export async function getStationOutfitting(marketIdOrSystemName: number | string, stationName?: string, params?: SystemIdRequestOptions):
+        Promise<StationOutfittingResponse> {
+    return getStationDetails<StationOutfittingResponse>("outfitting", marketIdOrSystemName, stationName, params);
+}
+
+export interface SystemFactionsOptions extends SystemIdRequestOptions {
+    /** Set to 1 to get the factions history under the requested system. */
+    showHistory?: number;
+}
+
+export interface ShortSystemFaction {
+    id: number;
+    name: string;
+    allegiance: string;
+    government: string;
+}
+
+export interface SystemFaction extends ShortSystemFaction {
+    influence: number;
+    influenceHistory?: Record<string, number> | [];
+    state: string;
+    stateHistory?: Record<string, string> | [];
+    activeStates: Array<{ state: string }>;
+    activeStatesHistory?: Record<string, Array<{ state: string }>> | [];
+    recoveringStates: Array<{ state: string, trend?: number }>;
+    recoveringStatesHistory?: Record<string, Array<{ state: string, trend?: number }>> | [];
+    pendingStates: Array<{ state: string, trend?: number }>;
+    pendingStatesHistory?: Record<string, Array<{ state: string, trend?: number }>> | [];
+    happiness: string;
+    happinessHistory?: Record<string, string> | [];
+    isPlayer: boolean;
+    lastUpdate: number;
+}
+
+/**
+ * Response structure of the EDSM system factions request.
+ */
+export interface SystemFactionsResponse {
+    id: number;
+    id64: Id64;
+    name: string;
+    url: string;
+    controllingFaction?: ShortSystemFaction;
+    factions: SystemFaction[];
+}
+
+/**
+ * Returns information about factions in a system.
+ *
+ * @param systemName - The system name.
+ * @param options    - Optional parameters.
+ * @returns The information about stations in a system.
+ * @throws NotFoundException - When system was not found.
+ */
+export async function getSystemFactions(systemName: string, options?: SystemFactionsOptions): Promise<SystemFactionsResponse> {
+    const response = await request<SystemFactionsResponse>("api-system-v1/factions", { systemName, ...options });
+    if (response == null) {
+        throw new NotFoundException(`System not found: ${systemName}`);
+    }
+    return response;
+}
+
+/**
+ * Response structure of the EDSM system traffic request.
+ */
+export interface SystemTrafficResponse {
+    id: number;
+    id64: Id64;
+    name: string;
+    url: string;
+    discovery: {
+        commander: string;
+        date: string;
+    };
+    traffic: {
+        total: number;
+        week: number;
+        day: number;
+    };
+    breakdown: Record<string, number>;
+}
+
+/**
+ * Returns information about traffic in a system.
+ *
+ * @param systemName - The system name.
+ * @param ids        - Optional parameters.
+ * @returns The information about traffic in a system.
+ * @throws NotFoundException - When system was not found.
+ */
+export async function getSystemTraffic(systemName: string, ids?: SystemIdRequestOptions): Promise<SystemTrafficResponse> {
+    const response = await request<SystemTrafficResponse>("api-system-v1/traffic", { systemName, ...ids });
+    if (response == null) {
+        throw new NotFoundException(`System not found: ${systemName}`);
+    }
+    return response;
+}
+
+/**
+ * Response structure of the EDSM system deaths request.
+ */
+export interface SystemDeathsResponse {
+    id: number;
+    id64: Id64;
+    name: string;
+    url: string;
+    deaths: {
+        total: number;
+        week: number;
+        day: number;
+    };
+}
+
+/**
+ * Returns information about deaths in a system.
+ *
+ * @param systemName - The system name.
+ * @param ids        - Optional parameters.
+ * @returns The information about deaths in a system.
+ * @throws NotFoundException - When system was not found.
+ */
+export async function getSystemDeaths(systemName: string, ids?: SystemIdRequestOptions): Promise<SystemDeathsResponse> {
+    const response = await request<SystemDeathsResponse>("api-system-v1/deaths", { systemName, ...ids });
+    if (response == null) {
+        throw new NotFoundException(`System not found: ${systemName}`);
+    }
+    return response;
+}

package/src/main/api/systems.ts

@@ -0,0 +1,199 @@
+/*
+ * Copyright (C) 2025 Klaus Reimer <k@ailis.de>
+ * See LICENSE.md for licensing information.
+ */
+
+import type { Coordinates, Id64 } from "../common.ts";
+import { NotFoundException } from "../util.ts";
+import { type SystemIdRequestOptions, request } from "./common.ts";
+
+/**
+ * Response of a {@link getSystem} request.
+ */
+export interface SystemResponse {
+    /** The name of the system. */
+    name: string;
+
+    /** The EDSM ID of the system. Only present when {@link SystemRequestOptions#showId} option is set to 1. */
+    id?: number;
+
+    /** The Frontier ID of the system. Only present when {@link SystemRequestOptions#showId} option is set to 1. */
+    id64?: Id64;
+
+    /**
+     * The systems ID having the exact same name in the game. Only present when there are duplicated and
+     * {@link SystemRequestOptions#showId} option is set to 1.
+     */
+    duplicates?: number[];
+
+    /** The coordinates of the system. Only present when {@link SystemRequestOptions#showCoordinates} option is set to 1. */
+    coords?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+
+    /**
+     * True when exact coords are known. False when position is trilaterated. Only present when {@link SystemRequestOptions#showCoordinates}
+     * option is set to 1
+     */
+    coordsLocked?: boolean;
+
+    /** System information. Only present when {@link SystemRequestOptions#showInformation} option is set to 1. */
+    information?: {
+        allegiance?: string;
+        government?: string;
+        faction?: string;
+        factionState?: string;
+        population?: number;
+        security?: string;
+        economy?: string;
+        secondEconomy?: string;
+        reserve?: string;
+    };
+
+    /** Permit information. Only present when {@link SystemRequestOptions#showPermit} option is set to 1. */
+    requirePermit?: boolean;
+
+    /** Permit name if any. Only present when {@link SystemRequestOptions#showPermit} option is set to 1. */
+    permitName?: string;
+
+    /** Information about the primary star if any. Only present when {@link SystemRequestOptions#showPrimaryStar} option is set to 1. */
+    primaryStar?: {
+        type: string;
+        name: string;
+        isScoopable: boolean;
+    };
+
+    /** The time when the system was hidden. Only present when system is hidden and {@link SystemRequestOptions#includeHidden} is set to 1 */
+    hidden_at?: string;
+
+    /**
+     * The system ID this system was merged to. Only present when system was merged and,  {@link SystemRequestOptions#includeHidden} is set to 1
+     * and {@link SystemRequestOptions#showId} is also set to 1.
+     */
+    mergedTo?: number;
+}
+
+/**
+ * Flags for enabling data in {@link SystemResponse}.
+ */
+export interface SystemRequestFlags {
+    /** Set to 1 to get our internal ID for this system. */
+    showId?: number;
+
+    /** Set to 1 to get the system coordinates. If coordinates are unknown, the coords key will not be returned. */
+    showCoordinates?: number;
+
+    /** Set to 1 to get the system permit if there is one. If the permit is named, also return permitName. */
+    showPermit?: number;
+
+    /** Set to 1 to get the system information like allegiance, government... If no information are stored, an empty object will be returned. */
+    showInformation?: number;
+
+    /** Set to 1 to get the system primary star if known. If no primary star is stored, null will be returned.  */
+    showPrimaryStar?: number;
+
+    /** Set to 1 to get system even if hidden in the database. Hidden system are generally typo errors, renamed system in the game... */
+    includeHidden?: number;
+}
+
+/**
+ * Options for {@link getSystem} request.
+ */
+export interface SystemRequestOptions extends SystemIdRequestOptions, SystemRequestFlags {}
+
+/**
+ * Returns information about the given system.
+ *
+ * @param systemName - The system name.
+ * @returns The system information.
+ * @throws NotFoundException - When system was not found.
+ */
+export async function getSystem(systemName: string, options?: SystemRequestOptions): Promise<SystemResponse> {
+    const system = await request<SystemResponse>("api-v1/system", { systemName, ...options });
+    if (system == null) {
+        throw new NotFoundException(`System not found: ${systemName}`);
+    }
+    return system;
+}
+
+/**
+ * Options for {@link getSystems} request.
+ */
+export interface SystemsRequestOptions extends SystemRequestFlags {
+    /** The systems name to retrieve, can be a start of a name or an array of specific names. */
+    systemName?: string | string[];
+
+    /**
+     * If you only want to receive systems updated after a specific date & time, use this parameter.
+     * Parameter is inclusive. All dates must be UTC.
+     * Format: YYYY-MM-DD HH:MM:SS.
+     */
+    startDateTime?: string;
+
+    /**
+     * If you only want to receive systems updated before a specific date & time, use this parameter.
+     * Parameter is inclusive. All dates must be UTC.
+     * Format: YYYY-MM-DD HH:MM:SS.
+     */
+    endDateTime?: string;
+
+    /** Set to 1 to get only systems with known coordinates. */
+    onlyKnownCoordinates?: number;
+
+    /** Set to 1 to get only systems without coordinates. */
+    onlyUnknownCoordinates?: number;
+}
+
+/**
+ * Returns information about multiple systems.
+ *
+ * @param options - The request options.
+ * @returns List of system information. Empty if none.
+ */
+export async function getSystems(options?: SystemsRequestOptions): Promise<SystemResponse[]> {
+    const system = await request<SystemResponse[]>("api-v1/systems", { ...options });
+    return system ?? [];
+}
+
+/**
+ * Options for {@link getSphereSystems} request.
+ */
+export interface SphereSystemsRequestOptions extends SystemRequestFlags, SystemIdRequestOptions {
+    /** Desired radius in LY. Defaults to 50, maximum is 100.  */
+    radius?: number;
+
+    /** The minimum radius in LY. Must be between 0 and {@link radius}. Defaults to 0. */
+    minRadius?: number;
+}
+
+/**
+ * Returns information about multiple systems in a given sphere.
+ *
+ * @param options - The request options.
+ * @returns List of system information in given sphere. Empty if none.
+ */
+export async function getSphereSystems(systemNameOrCoords: string | Coordinates, options?: SphereSystemsRequestOptions): Promise<SystemResponse[]> {
+    const center = typeof systemNameOrCoords === "string" ? { systemName: systemNameOrCoords } : systemNameOrCoords;
+    return (await request("api-v1/sphere-systems", { ...center, ...options }))!;
+}
+
+/**
+ * Options for {@link getCubeSystems} request.
+ */
+export interface CubeSystemsRequestOptions extends SystemRequestFlags, SystemIdRequestOptions {
+    /** Desired cube size in LY. Defaults to 100, maximum is 200.  */
+    size?: number;
+}
+
+/**
+ * Returns information about multiple systems in a given cube.
+ *
+ * @param options - The request options.
+ * @returns List of system information in given cube. Empty if none.
+ */
+export async function getCubeSystems(systemNameOrCoords: string | Coordinates, options?: CubeSystemsRequestOptions): Promise<SystemResponse[]> {
+    const center = typeof systemNameOrCoords === "string" ? { systemName: systemNameOrCoords } : systemNameOrCoords;
+    return (await request("api-v1/cube-systems", { ...center, ...options }))!;
+}

package/src/main/bodies.ts

@@ -0,0 +1,153 @@
+/*
+ * Copyright (C) 2018 Klaus Reimer <k@ailis.de>
+ * See LICENSE.md for licensing information.
+ */
+
+import type { Id64 } from "./common.ts";
+import { parseJSONArray } from "./util.ts";
+
+/**
+ * EDSM data about asteroid ring/belt.
+ */
+export interface Asteroids {
+    name: string;
+    type: string;
+    mass: number;
+    innerRadius: number;
+    outerRadius: number;
+}
+
+/**
+ * EDSM data about raw materials on a planet.
+ */
+export type Materials = Record<string, number>;
+/**
+ * EDSM data about solid composition of a planet.
+ */
+export type SolidComposition = Record<string, number>;
+
+/**
+ * EDSM data about atmosphere composition of a planet.
+ */
+export type  AtmosphereComposition = Record<string, number>;
+
+/**
+ * EDSM base body data shared by planets and stars.
+ */
+export interface BaseBody {
+    id: number;
+    id64: Id64 | null;
+    bodyId: number | null;
+    systemId: number;
+    systemId64: Id64;
+    systemName: string;
+    name: string;
+    discovery?: {
+        commander: string;
+        date: string;
+    };
+    subType: string;
+    parents: null | Array<
+        { Star: number } | { Planet: number } | { Null: number }
+    >;
+    distanceToArrival: number;
+    surfaceTemperature: number;
+    orbitalPeriod: number | null;
+    semiMajorAxis: number | null;
+    orbitalEccentricity: number | null;
+    orbitalInclination: number | null;
+    argOfPeriapsis: number | null;
+    rotationalPeriod: number | null;
+    rotationalPeriodTidallyLocked: boolean;
+    axialTilt: number | null;
+    rings?: Asteroids[];
+    reserveLevel?: string | null;
+    belts?: Asteroids[];
+    updateTime: string;
+}
+
+/**
+ * EDSM star data.
+ */
+export interface Star extends BaseBody {
+    type: "Star";
+    isMainStar?: boolean;
+    isScoopable?: boolean;
+    age: number;
+    spectralClass: string | null;
+    luminosity: string | null;
+    absoluteMagnitude: number;
+    solarMasses: number;
+    solarRadius: number;
+    surfaceTemperature: number;
+}
+
+/**
+ * EDSM planet data.
+ */
+export interface Planet extends BaseBody {
+    type: "Planet";
+    isLandable: boolean;
+    gravity: number;
+    earthMasses: number;
+    radius: number;
+    surfacePressure: number | null;
+    volcanismType: string | null;
+    atmosphereType: string | null;
+    atmosphereComposition: AtmosphereComposition | null;
+    solidComposition: SolidComposition | null;
+    terraformingState: string | null;
+    materials?: Materials;
+}
+
+/**
+ * Union type for EDSM star and planet data.
+ */
+export type Body = Planet | Star;
+
+export type SystemStar = Omit<Star, "systemId" | "systemId64" | "systemName">;
+export type SystemPlanet = Omit<Planet, "systemId" | "systemId64" | "systemName">;
+
+/**
+ * Body within a system (without system information because its already in the parent object)
+ */
+export type SystemBody = SystemStar | SystemPlanet;
+
+export function isPlanet(body: Body): body is Planet;
+export function isPlanet(body: SystemBody): body is SystemPlanet;
+
+/**
+ * Checks if given body is a planet.
+ *
+ * @param body - The body to check.
+ * @returns True if body is a planet.
+ */
+export function isPlanet(body: Body | SystemBody): boolean {
+    return body.type === "Planet";
+}
+
+export function isStar(body: Body): body is Star;
+export function isStar(body: SystemBody): body is SystemStar;
+
+/**
+ * Checks if given body is a planet.
+ *
+ * @param body - The body to check.
+ * @returns True if body is a star.
+ */
+export function isStar(body: Body | SystemBody): boolean {
+    return body.type === "Star";
+}
+
+/** List of EDSM bodies. */
+export type Bodies = Body[];
+
+/**
+ * Parses bodies from the given JSON stream.
+ *
+ * @param stream - The JSON input stream.
+ * @returns Stream of bodies.
+ */
+export function parseBodiesJSON(stream: AsyncIterable<Uint8Array>): AsyncIterable<Body> {
+    return parseJSONArray(stream);
+}