@kayahr/edsm 1.1.0

package/package.json

@@ -0,0 +1,82 @@
+{
+    "$schema": "http://json.schemastore.org/package",
+    "name": "@kayahr/edsm",
+    "version": "1.1.0",
+    "type": "module",
+    "description": "Typescript types and utility functions for the Elite Dangerous Star Map (EDSM) API",
+    "keywords": [
+        "elite dangerous",
+        "edsm",
+        "frontier"
+    ],
+    "license": "SEE LICENSE IN LICENSE.md",
+    "repository": "github:kayahr/edsm",
+    "publishConfig": {
+        "access": "public"
+    },
+    "author": {
+        "name": "Klaus Reimer",
+        "email": "k@ailis.de"
+    },
+    "funding": "https://github.com/kayahr/edsm?sponsor=1",
+    "files": [
+        "lib/main/",
+        "lib/*.schema.json",
+        "src/main/"
+    ],
+    "exports": "./lib/main/index.js",
+    "scripts": {
+        "clean": "rm -rf lib",
+        "build": "run build:*",
+        "build:compile": "tsc",
+        "build:schema": "run -p build:schema:*",
+        "build:schema:system-bodies-response": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t SystemBodiesResponse -o lib/system-bodies-response.schema.json",
+        "build:schema:system-estimated-value-response": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t SystemEstimatedValueResponse -o lib/system-estimated-value-response.schema.json",
+        "build:schema:system-stations-response": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t SystemStationsResponse -o lib/system-stations-response.schema.json",
+        "build:schema:system-factions-response": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t SystemFactionsResponse -o lib/system-factions-response.schema.json",
+        "build:schema:system-traffic-response": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t SystemTrafficResponse -o lib/system-traffic-response.schema.json",
+        "build:schema:system-deaths-response": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t SystemDeathsResponse -o lib/system-deaths-response.schema.json",
+        "build:schema:system-response": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t SystemResponse -o lib/system-response.schema.json",
+        "build:schema:station-market-response": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t StationMarketResponse -o lib/station-market-response.schema.json",
+        "build:schema:station-shipyard-response": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t StationShipyardResponse -o lib/station-shipyard-response.schema.json",
+        "build:schema:station-outfitting-response": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t StationOutfittingResponse -o lib/station-outfitting-response.schema.json",
+        "build:schema:elite-server-status-response": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t EliteServerStatusResponse -o lib/elite-server-status-response.schema.json",
+        "build:schema:flight-logs-response": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t FlightLogsResponse -o lib/flight-logs-response.schema.json",
+        "build:schema:commander-position-response": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t CommanderPositionResponse -o lib/commander-position-response.schema.json",
+        "build:schema:commander-ranks-response": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t CommanderRanksResponse -o lib/commander-ranks-response.schema.json",
+        "build:schema:commander-credits-response": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t CommanderCreditsResponse -o lib/commander-credits-response.schema.json",
+        "build:schema:commander-inventory-response": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t CommanderInventoryResponse -o lib/commander-inventory-response.schema.json",
+        "build:schema:system": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t System -o lib/system.schema.json",
+        "build:schema:station": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t Station -o lib/station.schema.json",
+        "build:schema:powerplay": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t PowerPlay -o lib/powerplay.schema.json",
+        "build:schema:codex": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t Codex -o lib/codex.schema.json",
+        "build:schema:body": "ts-json-schema-generator --no-type-check -e all -f tsconfig.json -t Body -o lib/body.schema.json",
+        "test": "run test:*",
+        "test:unit": "ntest",
+        "test:lint": "oxlint --type-aware --deny-warnings",
+        "test:apidoc": "typedoc --emit none",
+        "test:spell": "cspell --no-progress --no-summary",
+        "apidoc": "typedoc",
+        "site": "run apidoc site:*",
+        "site:clean": "rm -rf lib/site",
+        "site:apidoc": "cp -rf lib/apidoc lib/site ",
+        "site:schemas": "cp -f 'lib/*.schema.json' lib/site/schemas/",
+        "prepare": "run clean build"
+    },
+    "devDependencies": {
+        "@kayahr/assert": "1.3.2",
+        "@kayahr/cspell": "9.2.2-bundle.1",
+        "@kayahr/npm-utils": "1.1.1",
+        "@kayahr/ntest": "1.3.0",
+        "@kayahr/oxlint-config": "1.11.0",
+        "@kayahr/ts-json-schema-generator": "2.4.0-bundle.1",
+        "@kayahr/typedoc": "0.28.14-bundle.2",
+        "@types/node": "24.10.0",
+        "ajv": "8.17.1",
+        "fetch-mock": "12.6.0",
+        "typescript": "5.9.3"
+    },
+    "dependencies": {
+        "json-with-bigint": "^3.4.4"
+    }
+}

package/src/main/api/commander.ts

@@ -0,0 +1,116 @@
+/*
+ * Copyright (C) 2020 Klaus Reimer <k@ailis.de>
+ * See LICENSE.md for licensing information.
+ */
+
+import { request } from "./common.ts";
+
+/**
+ * Commander ranks response returned by {@link getCommanderRanks} request.
+ */
+export interface CommanderRanksResponse {
+    ranks: {
+        Combat: number;
+        Trade: number;
+        Explore: number;
+        Soldier: number;
+        Exobiologist: number;
+        CQC: number;
+        Federation: number;
+        Empire: number;
+    };
+    progress: {
+        Combat: number;
+        Trade: number;
+        Explore: number;
+        Soldier: number;
+        Exobiologist: number;
+        CQC: number;
+        Federation: number;
+        Empire: number;
+    };
+    ranksVerbose: {
+        Combat: string;
+        Trade: string;
+        Explore: string;
+        Soldier: string;
+        Exobiologist: string;
+        CQC: string;
+        Federation: string;
+        Empire: string;
+    };
+}
+
+/** Credits period type */
+export type CreditsPeriod = "7DAY" | "1MONTH" | "3MONTH" | "6MONTH";
+
+/**
+ * Commander credits response returned by {@link getCommanderCredits} request.
+ */
+export interface CommanderCreditsResponse {
+    credits: Array<{
+        balance: number;
+        loan: number;
+        date: string;
+    }>;
+    period?: CreditsPeriod;
+}
+
+/** Inventory type */
+export type InventoryType = "materials" | "data" | "cargo";
+
+/**
+ * Commander inventory response returned by {@link getCommanderInventory} request.
+ */
+export interface CommanderInventoryResponse {
+    materials?: Array<{
+        type: string | number;
+        name: string;
+        qty: number;
+    }>;
+    data?: Array<{
+        type: string | number;
+        name: string;
+        qty: number;
+    }>;
+    cargo?: Array<{
+        type: string | null;
+        name: string;
+        qty: number;
+    }>;
+}
+
+/**
+ * Returns commander ranks.
+ *
+ * @param commanderName - The name of the commander as registered on EDSM.
+ * @param apiKey        - The API key of the commander. If not provided, ranks will only be returned if the commander
+ *                        has enabled his public profile.
+ * @returns The commander ranks.
+ */
+export async function getCommanderRanks(commanderName: string, apiKey?: string): Promise<CommanderRanksResponse> {
+    return (await request<CommanderRanksResponse>("api-commander-v1/get-ranks", { commanderName, apiKey }))!;
+}
+
+/**
+ * Returns commander credits.
+ *
+ * @param commanderName - The name of the commander as registered on EDSM.
+ * @param apiKey        - The API key of the commander.
+ * @returns The commander credits.
+ */
+export async function getCommanderCredits(commanderName: string, apiKey: string, period?: CreditsPeriod): Promise<CommanderCreditsResponse> {
+    return (await request("api-commander-v1/get-credits", { commanderName, apiKey, period }))!;
+}
+
+/**
+ * Returns commander inventory.
+ *
+ * @param commanderName - The name of the commander as registered on EDSM.
+ * @param apiKey        - The API key of the commander.
+ * @param type          - The inventory type. Defaults to "materials".
+ * @returns The commander inventory.
+ */
+export async function getCommanderInventory(commanderName: string, apiKey: string, type?: InventoryType): Promise<CommanderInventoryResponse> {
+    return (await request("api-commander-v1/get-materials", { commanderName, apiKey, type }))!;
+}

package/src/main/api/common.ts

@@ -0,0 +1,77 @@
+/*
+ * Copyright (C) 2020 Klaus Reimer <k@ailis.de>
+ * See LICENSE.md for licensing information.
+ */
+
+import { JSONStringify } from "json-with-bigint";
+
+import type { Id64 } from "../common.ts";
+import { EDSMException, jsonReviver } from "../util.ts";
+
+export const edsmBaseUrl = "https://www.edsm.net";
+
+/**
+ * Request options for referencing a system via EDSM or Frontier ID instead of name. Needed when system name is not unique.
+ */
+export interface SystemIdRequestOptions {
+    /** The system ID if you seek for a duplicate system and want to force a specific ID. */
+    systemId?: number;
+
+    /** The system ID64 if you seek for a duplicate system and want to force a specific ID. */
+    systemId64?: Id64;
+}
+
+export class ServerException extends EDSMException {
+    public readonly status: number;
+
+    public constructor(status: number, message: string) {
+        super(message);
+        this.status = status;
+    }
+}
+
+export class APIException extends EDSMException {
+    public readonly status: number;
+
+    public constructor(status: number, message: string) {
+        super(message);
+        this.status = status;
+    }
+}
+
+interface MessageResult {
+    msgnum?: number;
+    msg?: string;
+}
+
+/**
+ * Sends JSON request to the given URL with the given parameters and returns the response.
+ *
+ * @param params - Optional parameters.
+ * @returns The JSON result. Null when result was an empty object which for EDSM means "not found".
+ * @throws APIException - When request failed for some unknown reason.
+ */
+export async function request<T>(url: string, params: Record<string, unknown> = {}): Promise<T | null> {
+    const result = await fetch(`${edsmBaseUrl}/${url}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSONStringify(params)
+    });
+    if (result.status !== 200) {
+        throw new ServerException(result.status, result.statusText);
+    }
+    const text = await result.text();
+    const json = JSON.parse(text, jsonReviver) as T & MessageResult;
+    if (json.msgnum != null && json.msg != null) {
+        if (json.msgnum < 100 || json.msgnum >= 200) {
+            throw new APIException(json.msgnum, json.msg);
+        } else {
+            delete json.msgnum;
+            delete json.msg;
+        }
+    }
+    if (Object.keys(json).length === 0) {
+        return null;
+    }
+    return json;
+}

package/src/main/api/journal.ts

@@ -0,0 +1,76 @@
+/*
+ * Copyright (C) 2025 Klaus Reimer <k@ailis.de>
+ * See LICENSE.md for licensing information.
+ */
+
+import type { Coordinates, Id64 } from "../common.ts";
+import { request } from "./common.ts";
+
+/**
+ * Response of a {@link sendEvents} request.
+ */
+export interface EventResponse {
+    /** Responses for each sent event. */
+    events: Array<{
+        /**
+         * 100 means the event was accepted. Every other code means the event was rejected for some reason.
+         * See https://www.edsm.net/en/api-journal-v1 for details.
+         */
+        msgnum: number;
+
+        /** Response code in text form. */
+        msg: string;
+
+        /** True if new system was created, false if not. */
+        systemCreated?: boolean;
+
+        /** EDSM system ID. */
+        systemId?: number;
+    }>;
+}
+
+/**
+ * Base data for EDSM event to be sent to EDSM. This must be the unmodified event read from the Journal, optionally enriched with additional
+ * context information.
+ */
+export interface EDSMEvent {
+    _systemAddress?: Id64;
+    _systemName?: string;
+    _systemCoordinates?: Coordinates;
+    _marketId?: number;
+    _stationName?: string;
+    _shipId?: number;
+    event: string;
+}
+
+/**
+ * Sends journal events to EDSM.
+ *
+ * @param commanderName        - The name of the commander as registered on EDSM.
+ * @param apiKey               - The API Key associated with the EDSM account.
+ * @param fromSoftware         - Name of the software (YOUR software using this library, not the name of this library!) used to submit the data.
+ * @param fromSoftwareVersion  - Version of the software used to submit the data.
+ * @param fromGameVersion      - Version of the game which generated the journal messages.
+ * @param fromGameBuild        - Build of the game which generated the journal messages.
+ * @param message              - The journal event (or multiple events to send).
+ */
+export async function sendEvents(commanderName: string, apiKey: string, fromSoftware: string, fromSoftwareVersion: string, fromGameVersion: string,
+        fromGameBuild: string, message: EDSMEvent | EDSMEvent[]): Promise<EventResponse> {
+    return (await request("api-journal-v1", {
+        apiKey,
+        fromSoftware,
+        fromSoftwareVersion,
+        fromGameVersion,
+        fromGameBuild,
+        message
+    }))!;
+}
+
+/**
+ * Returns the events which must be discarded from the list of journal events sent to EDSM.
+ *
+ * @returns The list of event names to be discarded.
+ */
+export async function getDiscardEvents(): Promise<string[]> {
+    return (await request("api-journal-v1/discard"))!;
+}

package/src/main/api/logs.ts

@@ -0,0 +1,166 @@
+/*
+ * Copyright (C) 2020 Klaus Reimer <k@ailis.de>
+ * See LICENSE.md for licensing information.
+ */
+
+import type { Coordinates, Id64 } from "../common.ts";
+import { type SystemIdRequestOptions, request } from "./common.ts";
+
+export interface FlightLog {
+    shipId: number | null;
+    system: string;
+    systemId?: number;
+    systemId64?: Id64;
+    firstDiscover: boolean;
+    date: string;
+}
+
+export interface FlightLogsResponse {
+    startDateTime: string;
+    endDateTime: string;
+    logs: FlightLog[];
+}
+
+export interface FlightLogFilter {
+    /** Filters flight logs by system name. */
+    systemName?: string;
+
+    /**
+     * Filters for flight logs after this date & time (inclusive). Must be specified in UTC in the format
+     * YYYY-MM-DD HH:MM:SS.
+     */
+    startDateTime?: string;
+
+    /**
+     * Filters for flight logs before this date & time (inclusive). Must be specified in UTC in the format
+     * YYYY-MM-DD HH:MM:SS.
+     */
+    endDateTime?: string;
+
+    /** Set to 1 if you want to get the EDSM internal id. Useful to handle duplicated name systems of the game. */
+    showId?: number;
+}
+
+/**
+ * Returns the flight log entries.
+ *
+ * @param commanderName - The name of the commander as registered on EDSM.
+ * @param apiKey        - The API key of the commander.
+ * @param filter        - Optional filter properties.
+ * @returns The flight log entries.
+ */
+export async function getFlightLogs(commanderName: string, apiKey: string, filter?: FlightLogFilter): Promise<FlightLogsResponse> {
+    return (await request("api-logs-v1/get-logs", { commanderName, apiKey, ...filter }))!;
+}
+
+/**
+ * Commander position response returned by {@link getCommanderPosition} request.
+ */
+export interface CommanderPositionResponse {
+    system: string | null;
+    systemId?: number;
+    systemId64?: Id64;
+    firstDiscover: boolean | null;
+    date: string | null;
+    coordinates?: Coordinates;
+    isDocked?: boolean;
+    station?: string;
+    stationId?: number;
+    dateDocked?: string;
+    shipId?: number;
+    shipType?: string;
+    shipFuel?: number | null;
+    dateLastActivity?: string;
+    url?: string;
+}
+
+export interface CommanderPositionOptions {
+    /**
+     * If not provided, information will only be returned if the commander has enabled his public profile, and share
+     * logs or map.
+     */
+    apiKey?: string;
+
+    /** Set to 1 if you want to get the EDSM internal id. Useful to handle duplicated name systems of the game. */
+    showId?: number;
+
+    /** Set to 1 if you want to get the coordinates of the system. */
+    showCoordinates?: number;
+}
+
+/**
+ * Returns the last position of the given commander.
+ *
+ * @param commanderName - The name of the commander as registered on EDSM.
+ * @param options       - Options.
+ * @returns The last position.
+ */
+export async function getCommanderPosition(commanderName: string, options?: CommanderPositionOptions): Promise<CommanderPositionResponse> {
+    return (await request("api-logs-v1/get-position", { commanderName, ...options }))!;
+}
+
+/** Response type of {@link setSystemComment} */
+export interface SystemCommentResponse {
+    comment: string | null;
+    lastUpdate: string | null;
+}
+
+/**
+ * Sets/Updates a comment.
+ *
+ * @param commanderName - The name of the commander as registered on EDSM.
+ * @param apiKey        - The API key associated with the commander.
+ * @param systemName    - The system name for which to set a comment.
+ * @param comment       - The comment to set. Empty string to remove.
+ * @param options       - Additional options.
+ */
+export async function setSystemComment(commanderName: string, apiKey: string, systemName: string, comment: string, options?: SystemIdRequestOptions):
+        Promise<SystemCommentResponse> {
+    return (await request("api-logs-v1/set-comment", { commanderName, apiKey, systemName, comment, ...options }))!;
+}
+
+/**
+ * Returns a system comment.
+ *
+ * @param commanderName - The name of the commander as registered on EDSM.
+ * @param apiKey        - The API key associated with the commander.
+ * @param systemName    - The system name for which to return the comment.
+ * @param options       - Additional options.
+ */
+export async function getSystemComment(commanderName: string, apiKey: string, systemName: string, options?: SystemIdRequestOptions):
+        Promise<SystemCommentResponse> {
+    return (await request("api-logs-v1/get-comment", { commanderName, apiKey, systemName, ...options }))!;
+}
+
+/** Response of a {@link getSystemComments} request. */
+export interface SystemCommentsResponse {
+    comments: Array<{
+        system: string;
+        systemId?: number;
+        comment: string;
+        lastUpdate: string;
+    }>;
+}
+
+/** Options for {@link getSystemComments} request. */
+export interface SystemCommentsOptions {
+    /**
+     * If you only want to receive comments updated after a specific date & time, use this parameter.
+     * That parameter is inclusive. All dates must be UTC.
+     */
+    startDateTime?: string;
+
+    /** Set to 1 if you want to get the EDSM internal id. Useful to handle duplicated name systems of the game. */
+    showId?: number;
+}
+
+/**
+ * Returns comments set for various systems.
+ *
+ * @param commanderName - The name of the commander as registered on EDSM.
+ * @param apiKey        - The API key associated with the commander.
+ * @param options       - Additional options.
+ */
+export async function getSystemComments(commanderName: string, apiKey: string, options?: SystemCommentsOptions): Promise<SystemCommentsResponse> {
+    return (await request("api-logs-v1/get-comments", { commanderName, apiKey, ...options }))!;
+}

package/src/main/api/status.ts

@@ -0,0 +1,24 @@
+/*
+ * Copyright (C) 2020 Klaus Reimer <k@ailis.de>
+ * See LICENSE.md for licensing information.
+ */
+
+import { request } from "./common.ts";
+
+export type EliteServerStatusType = "success" | "warning" | "danger";
+
+export interface EliteServerStatusResponse {
+    lastUpdate: string;
+    type: EliteServerStatusType;
+    message: string;
+    status: number;
+}
+
+/**
+ * Returns the elite server status.
+ *
+ * @returns The elite server status.
+ */
+export async function getEliteServerStatus(): Promise<EliteServerStatusResponse> {
+    return (await request("api-status-v1/elite-server"))!;
+}