@elite-dangerous-plugin-framework/journal 0.20250914.0 → 0.20260201.1

package/README.md

@@ -1,6 +1,84 @@
-# Elite Dangerous Journal Schemas
+# edpf-journal
 
 This module contains autogenerated Type definitions for the Elite: Dangerous Journal.
 This uses https://jixxed.github.io/ed-journal-schemas/ as its source of Schemas.
 
 Besides the Type definitions, this module contains 2 helper functions which will parse the Journal Entry with either BigInts or regular IEEE 754 64-bit floats for integers.
+
+This repository contains the conversion and generator code for https://www.npmjs.com/package/@elite-dangerous-plugin-framework/journal.
+
+## Installation
+
+```sh
+npm install @elite-dangerous-plugin-framework/journal
+pnpm install @elite-dangerous-plugin-framework/journal
+bun install @elite-dangerous-plugin-framework/journal
+# or your preferred package manager
+```
+
+## Usage
+
+```ts
+import {
+  parseWithBigInt,
+  parseWithLossyIntegers,
+} from "@elite-dangerous-plugin-framework/journal";
+// if you need type tree-shaking, you can directly import the events individually using their default export.
+// This works for regular and "bi" (bigint) event variant.
+import type SendText from "@elite-dangerous-plugin-framework/journal/events/SendText";
+import type SendTextBI from "@elite-dangerous-plugin-framework/journal/events/bi/SendText";
+
+const input = `
+{ "timestamp":"2026-02-01T01:08:59Z", "event":"RefuelAll", "Cost":79, "Amount":1.557032 }
+{ "timestamp":"2026-02-01T01:08:59Z", "event":"RepairAll", "Cost":23485 }
+{ "timestamp":"2026-02-01T01:09:12Z", "event":"Market", "MarketID":3701213952, "StationName":"V8V-86F", "StationType":"FleetCarrier", "CarrierDockingAccess":"all", "StarSystem":"Lysoorb NH-M d7-26" }
+{ "timestamp":"2026-02-01T01:12:50Z", "event":"Music", "MusicTrack":"SystemMap" }
+{ "timestamp":"2026-02-01T01:13:40Z", "event":"Music", "MusicTrack":"Exploration" }
+{ "timestamp":"2026-02-01T01:13:42Z", "event":"Music", "MusicTrack":"GalaxyMap" }
+{ "timestamp":"2026-02-01T01:14:05Z", "event":"Music", "MusicTrack":"Exploration" }
+{ "timestamp":"2026-02-01T01:14:19Z", "event":"Shutdown" }
+`
+  .split("\n")
+  .map((e) => e.trim())
+  // removing empty lines
+  .filter(Boolean)
+
+// All non-float numbers are converted to BigInts. Use this if
+// you rely on IDs, as the regular number type is not precise enough
+const parsedWithBigIntSupport = input.map((e) => parseWithBigInt(e)).forEach(e => {
+    switch(e.event) {
+        // parseWithBigInt / parseWithLossyIntegers returns a JournalEvent_BI / JournalEvent
+        // it's event property can be switched on, which will give you strong typing for the relevant event.
+        case "WingJoin": ...
+        case "WingLeave": ...
+        case "WingAdd": ...
+        case ...
+        ...
+    }
+})
+const parsedWithRegularNumbers = input.map((e) => parseWithLossyIntegers(e));
+
+function someFunctionThatWantsAMessageSent(msg: SendText | SendTextBI) {
+  console.log(
+    `You wrote in channel ${msg.To} at ${msg.timestamp}: ${msg.Message} `,
+  );
+}
+```
+
+`JournalEvent` and `JournalEvent_BI` combine all events into one. It is essentially a huge Type union.
+All events have two shared properties: `timestamp` and `event`. You can filter on the `event` field to expose the other properties.
+![Example image showing strong typing](README-src/strongTypingExample.png)
+![Second example detailling that you do get the event's structure](README-src/strongTypingExample2.png)
+
+## Versioning
+
+Other than the other packages that reside in the `@elite-dangerous-plugin-framework` namespace, this package uses calendar-versioning.
+
+The Version has the format `0.YYYYMMDD.X` where X is a counter starting at 0 for that specific day in UTC time.
+
+## Contributing
+
+Are some journal items incorrect? Then [please contribute upstream](https://jixxed.github.io/ed-journal-schemas/).
+Else, PRs are always welcome.
+
+If you have any questions, please don't hesitate to get into contact. Do note you will get a quicker response by contacting via Discord. Ping `wdx` in the [EDCD Discord](https://discord.gg/zQjjutY) for support.

package/dist/generated/CancelledSquadronApplication.bi.d.ts

@@ -0,0 +1,24 @@
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+type CancelledSquadronApplicationEvent_BI = Event & {
+    SquadronID: SquadronID;
+    SquadronName: SquadronName;
+};
+/**
+ * Timestamp in UTC, ISO 8601
+ */
+type Timestamp = string;
+type Event1 = "CancelledSquadronApplication";
+type SquadronID = bigint;
+type SquadronName = string;
+/**
+ * Generic Event
+ */
+interface Event {
+    timestamp: Timestamp;
+    event: Event1;
+}
+export default CancelledSquadronApplicationEvent_BI;

package/dist/generated/CancelledSquadronApplication.d.ts

@@ -0,0 +1,24 @@
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+type CancelledSquadronApplicationEvent = Event & {
+    SquadronID: SquadronID;
+    SquadronName: SquadronName;
+};
+/**
+ * Timestamp in UTC, ISO 8601
+ */
+type Timestamp = string;
+type Event1 = "CancelledSquadronApplication";
+type SquadronID = number;
+type SquadronName = string;
+/**
+ * Generic Event
+ */
+interface Event {
+    timestamp: Timestamp;
+    event: Event1;
+}
+export default CancelledSquadronApplicationEvent;

package/dist/generated/CompleteConstruction.bi.d.ts

@@ -0,0 +1,22 @@
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+/**
+ * When written: upon completing a colonisation construction
+ */
+type CompleteConstructionEvent_BI = Event;
+/**
+ * Timestamp in UTC, ISO 8601
+ */
+type Timestamp = string;
+type Event1 = "CompleteConstruction";
+/**
+ * Generic Event
+ */
+interface Event {
+    timestamp: Timestamp;
+    event: Event1;
+}
+export default CompleteConstructionEvent_BI;

package/dist/generated/CompleteConstruction.d.ts

@@ -0,0 +1,22 @@
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+/**
+ * When written: upon completing a colonisation construction
+ */
+type CompleteConstructionEvent = Event;
+/**
+ * Timestamp in UTC, ISO 8601
+ */
+type Timestamp = string;
+type Event1 = "CompleteConstruction";
+/**
+ * Generic Event
+ */
+interface Event {
+    timestamp: Timestamp;
+    event: Event1;
+}
+export default CompleteConstructionEvent;

package/dist/generated/Docked.bi.d.ts

@@ -15,7 +15,7 @@ type DockedEvent_BI = Event & {
     StarSystem: StarSystem;
     SystemAddress: SystemAddress;
     MarketID: MarketID;
-    StationFaction: StationFaction;
+    StationFaction?: StationFaction;
     StationGovernment: StationGovernment;
     StationGovernment_Localised?: StationGovernment_Localised;
     StationServices: StationServices;

package/dist/generated/Docked.d.ts

@@ -15,7 +15,7 @@ type DockedEvent = Event & {
     StarSystem: StarSystem;
     SystemAddress: SystemAddress;
     MarketID: MarketID;
-    StationFaction: StationFaction;
+    StationFaction?: StationFaction;
     StationGovernment: StationGovernment;
     StationGovernment_Localised?: StationGovernment_Localised;
     StationServices: StationServices;

package/dist/generated/PowerplayMerits.bi.d.ts

@@ -4,7 +4,7 @@
  * and run json-schema-to-typescript to regenerate this file.
  */
 /**
- * When written: when receiving salary payment from a power
+ * When written: when receiving merits from a power
  */
 type PowerplayMeritsEvent_BI = Event & {
     Power: Power;

package/dist/generated/PowerplayMerits.d.ts

@@ -4,7 +4,7 @@
  * and run json-schema-to-typescript to regenerate this file.
  */
 /**
- * When written: when receiving salary payment from a power
+ * When written: when receiving merits from a power
  */
 type PowerplayMeritsEvent = Event & {
     Power: Power;

package/dist/generated/PowerplayRank.bi.d.ts

@@ -4,7 +4,7 @@
  * and run json-schema-to-typescript to regenerate this file.
  */
 /**
- * When written: when receiving salary payment from a power
+ * When written: when ranking up with a power
  */
 type PowerplayRankEvent_BI = Event & {
     Power: Power;

package/dist/generated/PowerplayRank.d.ts

@@ -4,7 +4,7 @@
  * and run json-schema-to-typescript to regenerate this file.
  */
 /**
- * When written: when receiving salary payment from a power
+ * When written: when ranking up with a power
  */
 type PowerplayRankEvent = Event & {
     Power: Power;

package/dist/generated/Scan.bi.d.ts

@@ -39,6 +39,7 @@ type ScanEvent_BI = Event & {
     AxialTilt?: AxialTilt;
     WasDiscovered: WasDiscovered;
     WasMapped: WasMapped;
+    WasFootfalled?: WasFootfalled;
     StarType?: StarType;
     Subclass?: Subclass;
     StellarMass?: StellarMass;
@@ -195,6 +196,7 @@ type WasDiscovered = boolean;
  * Written for Star/Planet/Moon
  */
 type WasMapped = boolean;
+type WasFootfalled = boolean;
 /**
  * Written for Star
  */

package/dist/generated/Scan.d.ts

@@ -39,6 +39,7 @@ type ScanEvent = Event & {
     AxialTilt?: AxialTilt;
     WasDiscovered: WasDiscovered;
     WasMapped: WasMapped;
+    WasFootfalled?: WasFootfalled;
     StarType?: StarType;
     Subclass?: Subclass;
     StellarMass?: StellarMass;
@@ -195,6 +196,7 @@ type WasDiscovered = boolean;
  * Written for Star/Planet/Moon
  */
 type WasMapped = boolean;
+type WasFootfalled = boolean;
 /**
  * Written for Star
  */

package/dist/generated/ScanOrganic.bi.d.ts

@@ -14,6 +14,7 @@ type ScanOrganicEvent_BI = Event & {
     Species_Localised?: Species_Localised;
     Variant?: Variant;
     Variant_Localised?: Variant_Localised;
+    WasLogged?: WasLogged;
     SystemAddress: SystemAddress;
     Body: Body;
 };
@@ -29,6 +30,7 @@ type Species = string;
 type Species_Localised = string;
 type Variant = string;
 type Variant_Localised = string;
+type WasLogged = boolean;
 type SystemAddress = bigint;
 type Body = bigint;
 /**

package/dist/generated/ScanOrganic.d.ts

@@ -14,6 +14,7 @@ type ScanOrganicEvent = Event & {
     Species_Localised?: Species_Localised;
     Variant?: Variant;
     Variant_Localised?: Variant_Localised;
+    WasLogged?: WasLogged;
     SystemAddress: SystemAddress;
     Body: Body;
 };
@@ -29,6 +30,7 @@ type Species = string;
 type Species_Localised = string;
 type Variant = string;
 type Variant_Localised = string;
+type WasLogged = boolean;
 type SystemAddress = number;
 type Body = number;
 /**

package/dist/generated/SendText.bi.d.ts

@@ -8,6 +8,7 @@
  */
 type SendTextEvent_BI = Event & {
     To: To;
+    To_Localised?: To_Localised;
     Message: Message;
     Sent: Sent;
 };
@@ -17,6 +18,10 @@ type SendTextEvent_BI = Event & {
 type Timestamp = string;
 type Event1 = "SendText";
 type To = string;
+/**
+ * Unclear under which conditions this field is present, but it sometimes is.
+ */
+type To_Localised = string;
 type Message = string;
 type Sent = boolean;
 /**

package/dist/generated/SendText.d.ts

@@ -8,6 +8,7 @@
  */
 type SendTextEvent = Event & {
     To: To;
+    To_Localised?: To_Localised;
     Message: Message;
     Sent: Sent;
 };
@@ -17,6 +18,10 @@ type SendTextEvent = Event & {
 type Timestamp = string;
 type Event1 = "SendText";
 type To = string;
+/**
+ * Unclear under which conditions this field is present, but it sometimes is.
+ */
+type To_Localised = string;
 type Message = string;
 type Sent = boolean;
 /**

package/dist/generated/SquadronApplicationApproved.bi.d.ts

@@ -0,0 +1,24 @@
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+type SquadronApplicationApprovedEvent_BI = Event & {
+    SquadronID: SquadronID;
+    SquadronName: SquadronName;
+};
+/**
+ * Timestamp in UTC, ISO 8601
+ */
+type Timestamp = string;
+type Event1 = "SquadronApplicationApproved";
+type SquadronID = bigint;
+type SquadronName = string;
+/**
+ * Generic Event
+ */
+interface Event {
+    timestamp: Timestamp;
+    event: Event1;
+}
+export default SquadronApplicationApprovedEvent_BI;

package/dist/generated/SquadronApplicationApproved.d.ts

@@ -0,0 +1,24 @@
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+type SquadronApplicationApprovedEvent = Event & {
+    SquadronID: SquadronID;
+    SquadronName: SquadronName;
+};
+/**
+ * Timestamp in UTC, ISO 8601
+ */
+type Timestamp = string;
+type Event1 = "SquadronApplicationApproved";
+type SquadronID = number;
+type SquadronName = string;
+/**
+ * Generic Event
+ */
+interface Event {
+    timestamp: Timestamp;
+    event: Event1;
+}
+export default SquadronApplicationApprovedEvent;

package/dist/generated/SquadronApplicationRejected.bi.d.ts

@@ -0,0 +1,24 @@
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+type SquadronApplicationRejectedEvent_BI = Event & {
+    SquadronID: SquadronID;
+    SquadronName: SquadronName;
+};
+/**
+ * Timestamp in UTC, ISO 8601
+ */
+type Timestamp = string;
+type Event1 = "SquadronApplicationRejected";
+type SquadronID = bigint;
+type SquadronName = string;
+/**
+ * Generic Event
+ */
+interface Event {
+    timestamp: Timestamp;
+    event: Event1;
+}
+export default SquadronApplicationRejectedEvent_BI;

package/dist/generated/SquadronApplicationRejected.d.ts

@@ -0,0 +1,24 @@
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+type SquadronApplicationRejectedEvent = Event & {
+    SquadronID: SquadronID;
+    SquadronName: SquadronName;
+};
+/**
+ * Timestamp in UTC, ISO 8601
+ */
+type Timestamp = string;
+type Event1 = "SquadronApplicationRejected";
+type SquadronID = number;
+type SquadronName = string;
+/**
+ * Generic Event
+ */
+interface Event {
+    timestamp: Timestamp;
+    event: Event1;
+}
+export default SquadronApplicationRejectedEvent;

package/dist/generated/Status.bi.d.ts

@@ -35,21 +35,116 @@ type StatusEvent_BI = Event & {
  */
 type Timestamp = string;
 type Event1 = "Status";
+/**
+ * Flags:
+ * Bit Value      Hex       Meaning
+ * 0   1          0000 0001 Docked, (on a landing pad)
+ * 1   2          0000 0002 Landed, (on planet surface)
+ * 2   4          0000 0004 Landing Gear Down
+ * 3   8          0000 0008 Shields Up
+ * 4   16         0000 0010 Supercruise
+ * 5   32         0000 0020 FlightAssist Off
+ * 6   64         0000 0040 Hardpoints Deployed
+ * 7   128        0000 0080 In Wing
+ * 8   256        0000 0100 LightsOn
+ * 9   512        0000 0200 Cargo Scoop Deployed
+ * 10  1024       0000 0400 Silent Running,
+ * 11  2048       0000 0800 Scooping Fuel
+ * 12  4096       0000 1000 Srv Handbrake
+ * 13  8192       0000 2000 Srv using Turret view
+ * 14  16384      0000 4000 Srv Turret retracted (close to ship)
+ * 15  32768      0000 8000 Srv DriveAssist
+ * 16  65536      0001 0000 Fsd MassLocked
+ * 17  131072     0002 0000 Fsd Charging
+ * 18  262144     0004 0000 Fsd Cooldown
+ * 19  524288     0008 0000 Low Fuel ( < 25% )
+ * 20  1048576    0010 0000 Over Heating ( > 100% )
+ * 21  2097152    0020 0000 Has Lat Long
+ * 22  4194304    0040 0000 IsInDanger
+ * 23  8388608    0080 0000 Being Interdicted
+ * 24  16777216   0100 0000 In MainShip
+ * 25  33554432   0200 0000 In Fighter
+ * 26  67108864   0400 0000 In SRV
+ * 27  134217728  0800 0000 Hud in Analysis mode
+ * 28  268435456  1000 0000 Night Vision
+ * 29  536870912  2000 0000 Altitude from Average radius
+ * 30  1073741824 4000 0000 fsdJump
+ * 31  2147483648 8000 0000 srvHighBeam
+ */
 type Flags = bigint;
+/**
+ * an array of 3 integers representing energy distribution (in half-pips)
+ */
 type Pips = number[];
 type FireGroup = bigint;
 type FuelMain = number;
 type FuelReservoir = number;
+/**
+ * the selected GUI screen
+ * 0  NoFocus
+ * 1  InternalPanel (right hand side)
+ * 2  ExternalPanel (left hand side)
+ * 3  CommsPanel (top)
+ * 4  RolePanel (bottom)
+ * 5  StationServices
+ * 6  GalaxyMap
+ * 7  SystemMap
+ * 8  Orrery
+ * 9  FSS mode
+ * 10 SAA mode
+ * 11 Codex
+ */
 type GuiFocus = bigint;
+/**
+ * if on or near a planet
+ * The latitude or longitude need to change by 0.02 degrees to trigger an update when flying, or by 0.0005 degrees when in the SRV. If the bit29 is set, the altitude value is based on the planet’s average radius (used at higher altitudes). If the bit29 is not set, the Altitude value is based on a raycast to the actual surface below the ship/srv
+ */
 type Latitude = number;
+/**
+ * if on or near a planet
+ * The latitude or longitude need to change by 0.02 degrees to trigger an update when flying, or by 0.0005 degrees when in the SRV. If the bit29 is set, the altitude value is based on the planet’s average radius (used at higher altitudes). If the bit29 is not set, the Altitude value is based on a raycast to the actual surface below the ship/srv
+ */
 type Longitude = number;
 type Heading = bigint;
 type Altitude = bigint;
+/**
+ * Flags2:
+ * Bit Value      Hex       Meaning
+ * 0   1          0000 0001 OnFoot
+ * 1   2          0000 0002 InTaxi (or dropship/shuttle)
+ * 2   4          0000 0004 InMulticrew (ie in someone else’s ship)
+ * 3   8          0000 0008 OnFootInStation
+ * 4   16         0000 0010 OnFootOnPlanet
+ * 5   32         0000 0020 AimDownSight
+ * 6   64         0000 0040 LowOxygen
+ * 7   128        0000 0080 LowHealth
+ * 8   256        0000 0100 Cold
+ * 9   512        0000 0200 Hot
+ * 10  1024       0000 0400 VeryCold
+ * 11  2048       0000 0800 VeryHot
+ * 12  4096       0000 1000 Glide Mode
+ * 13  8192       0000 2000 OnFootInHangar
+ * 14  16384      0000 4000 OnFootSocialSpace
+ * 15  32768      0000 8000 OnFootExterior
+ * 16  65536      0001 0001 BreathableAtmosphere
+ * 17  131072     0002 0000 Telepresence Multicrew
+ * 18  262144     0004 0000 Physical Multicrew
+ * 19  524288     0008 0000 Fsd hyperdrive charging
+ * 20  1048576    0010 0000 Supercruise Overcharge
+ * 21  2097152    0020 0000 Supercruise Assist
+ * 22  4194304    0040 0000 NPC Crew Active
+ */
 type Flags2 = bigint;
 type Cargo = number;
 type LegalState = string;
 type Balance = bigint;
+/**
+ * value range: 0.0 - 1.0
+ */
 type Oxygen = number;
+/**
+ * value range: 0.0 - 1.0
+ */
 type Health = number;
 type Temperature = number;
 type SelectedWeapon = string;
@@ -60,6 +155,9 @@ type Name = string;
 type Name_Localised = string;
 type PlanetRadius = number;
 type SelectedWeapon_Localised = string;
+/**
+ * relative to 1G
+ */
 type Gravity = number;
 /**
  * Generic Event