@elite-dangerous-almanac/core 0.1.0-beta.1

package/dist/ships/slots.d.ts

@@ -0,0 +1,418 @@
+/**
+ * The **slot model** for a ship build — data-free types and helpers that describe
+ * where modules go on a hull and reconcile the two ways a slot is named.
+ *
+ * A hull offers a fixed set of mounts: seven core internals, a handful of weapon
+ * hardpoints, some tiny utility mounts, and a column of optional internals. Some of
+ * those mounts are **restricted** to one family of modules — military and
+ * planetary-approach optionals on most hulls, and, on three hulls, cargo-only,
+ * limpet-controller-only, vessel-hangar-only and passenger-cabin-only optionals and
+ * mining-only hardpoints (see {@link SlotRestriction}). This module gives
+ * each mount a stable **slot key** and a {@link BuildSlot} descriptor, and
+ * {@link parseSlotName} classifies a journal slot name (as it appears in a SLEF
+ * export) into the same shape — so a build loaded from SLEF and a build assembled from
+ * scratch speak one vocabulary.
+ *
+ * It holds no data; {@link enumerateSlots} takes a {@link ShipSlots} layout (from a
+ * hull's `Ship` record via `getShipSlots` in `./ships`) and expands it into keyed
+ * {@link BuildSlot}s. Most hulls number their mounts by rule; on ten the game does
+ * not, and a mount there carries its own `name` — see {@link enumerateSlots}.
+ *
+ * @packageDocumentation
+ */
+/** The kind of mount a slot is. */
+type SlotKind = 'core' | 'hardpoint' | 'utility' | 'optional' | 'armour' | 'cargoHatch';
+/**
+ * A restriction limiting which weapons a **hardpoint** accepts.
+ *
+ * @remarks
+ * Only the Type-11 Prospector has any: four of its eight mounts take mining tools
+ * (mining lasers and the Mining Lance, abrasion blasters, seismic charge launchers,
+ * sub-surface displacement and extraction missiles, and the Mining Volley Repeater)
+ * and nothing else. The journal names such a mount with a `Mining` infix —
+ * `LargeMiningHardpoint1` — so {@link parseSlotName} recognises one on sight.
+ */
+type HardpointRestriction = 'mining';
+/**
+ * A restriction limiting which **optional-internal** modules a slot accepts.
+ *
+ * - `military` — hull, module, shield and Guardian reinforcement packages and shield
+ *   cell banks (journal `Military01`).
+ * - `planetaryApproachSuite` — the approach suite alone, which in turn fits nowhere
+ *   else (journal `PlanetaryApproachSuite`).
+ * - `cargo` — cargo racks (ordinary, Mk II and corrosion-resistant) and fuel tanks;
+ *   the Panther Clipper Mk II's first size-8 and first size-7 optionals (journal
+ *   `Cargo01` and `Cargo02`).
+ * - `limpetController` — any limpet controller, single-purpose or multi (the Type-11
+ *   Prospector's size-5 optional; journal `LimpetController01`).
+ * - `vesselHangar` — Mk I and Mk II vessel hangars (the Type-11 Prospector's other
+ *   size-5 optional; journal `FighterBay01`).
+ * - `passenger` — passenger cabins, Mk I and Mk II, at every class either family
+ *   offers (the Lynx Highliner's two size-6 and one size-5 optionals; journal
+ *   `Passenger01`–`Passenger03`).
+ */
+type OptionalRestriction = 'military' | 'planetaryApproachSuite' | 'cargo' | 'limpetController' | 'vesselHangar' | 'passenger';
+/**
+ * A restriction limiting which modules a slot accepts — every value either kind of
+ * restricted mount can carry.
+ *
+ * @remarks
+ * A {@link BuildSlot} is discriminated by `kind`: a `hardpoint` only carries a
+ * {@link HardpointRestriction}, an `optional` only an {@link OptionalRestriction}, and
+ * a `core` carries no restriction. Checking `slot.kind` narrows these fields.
+ *
+ * The list is complete. No hardpoint is restricted to one *mount* (fixed, gimballed or
+ * turret), and no utility mount is restricted.
+ *
+ * The journal spells two of these differently from the value: `vesselHangar` mounts
+ * are named `FighterBay01`, and
+ * `planetaryApproachSuite` is the only one whose key carries no number.
+ */
+type SlotRestriction = HardpointRestriction | OptionalRestriction;
+/**
+ * What each restriction accepts, as a short phrase fit for an outfitting UI.
+ *
+ * @remarks
+ * This is the same wording `ShipLoadout.setModule` uses when it refuses a module, so
+ * a label you show and the error a consumer sees cannot drift apart. It describes the
+ * module *families* a mount takes; for the actual fitting records, call
+ * `ShipLoadout.modulesForSlot`.
+ * @example
+ * ```ts
+ * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+ * import { SLOT_RESTRICTION_LABELS } from '@elite-dangerous-almanac/core/ships/slots';
+ *
+ * const slot = ShipLoadout.empty('LakonMiner').slots('hardpoint')[0]!;
+ * slot.restriction && SLOT_RESTRICTION_LABELS[slot.restriction]; // -> 'mining tools'
+ * ```
+ */
+declare const SLOT_RESTRICTION_LABELS: Readonly<Record<SlotRestriction, string>>;
+/**
+ * The seven fixed core-internal mounts, by function.
+ *
+ * @remarks
+ * These are **not** slot keys. A core mount has two names: this camelCase *function*
+ * (`BuildSlot.core`) and the journal's PascalCase *slot key* (`BuildSlot.key`), which
+ * is what every `slotKey` argument wants. Two of the pairs are not even the same word:
+ *
+ * | `core` (function) | `key` (journal slot) |
+ * | --- | --- |
+ * | `powerPlant` | `PowerPlant` |
+ * | `thrusters` | `MainEngines` |
+ * | `frameShiftDrive` | `FrameShiftDrive` |
+ * | `lifeSupport` | `LifeSupport` |
+ * | `powerDistributor` | `PowerDistributor` |
+ * | `sensors` | `Radar` |
+ * | `fuelTank` | `FuelTank` |
+ */
+type CoreSlotType = 'powerPlant' | 'thrusters' | 'frameShiftDrive' | 'lifeSupport' | 'powerDistributor' | 'sensors' | 'fuelTank';
+/**
+ * The fixed mount a module is built for — {@link OutfittingModule.slot}.
+ *
+ * @remarks
+ * The eight core-internal mounts every hull has: the seven {@link CoreSlotType}
+ * functions plus `armour`, which is a fixed mount too but is sized per hull rather
+ * than by class, and so is not one of the seven.
+ *
+ * A module carries this when it fills one particular mount and nothing else. Most do
+ * not: a hardpoint weapon, a utility fitting and an optional internal each fit any
+ * mount of their kind that is big enough, so there is no one mount to name.
+ *
+ * Two records bend a rule each. A fuel tank bends this one — it is `fuelTank` and fits
+ * any optional slot as well, the one module built for two kinds of mount. The Guardian
+ * Hybrid power plants and distributors bend "a core module lives in `CORE_MODULES`":
+ * they carry `powerPlant` / `powerDistributor` from `INTERNAL_MODULES`, which is where
+ * Frontier's registry files them.
+ */
+type ModuleSlot = CoreSlotType | 'armour';
+/**
+ * The stable identity and size shared by every hull mount.
+ *
+ * Use {@link BuildSlot} when the mount kind and its narrowed `core` or `restriction`
+ * field matter. This base is useful for consumers that only display or persist a slot
+ * key and size.
+ */
+interface BuildSlotBase {
+    /**
+     * Stable, journal-compatible slot key, e.g. `"PowerPlant"`, `"HugeHardpoint1"`,
+     * `"TinyHardpoint2"`, `"Slot01_Size6"`, `"Military01"`,
+     * `"PlanetaryApproachSuite"`, and on a restricted mount
+     * `"LargeMiningHardpoint1"`, `"Cargo01"`, `"LimpetController01"`,
+     * `"FighterBay01"`, `"Passenger01"`.
+     *
+     * @remarks
+     * This is the string every `slotKey` argument takes. It is matched
+     * **case-insensitively** and otherwise exactly — no surrounding whitespace, no
+     * abbreviation — because a SLEF producer may lower-case the game's own identifier,
+     * as the specification's own example does. Enumerate keys with
+     * `ShipLoadout.slots()` rather than typing them. Note a core {@link BuildSlot}'s
+     * `core` function name is a *different* string (`thrusters` vs the key
+     * `MainEngines`); see {@link CoreSlotType}.
+     *
+     * **Do not compute one.** The numbering looks regular and on ten hulls is
+     * not: the Anaconda's smallest optionals are `Slot13_Size2` and `Slot14_Size1`
+     * with no slots 11 or 12, the Type-9 Heavy starts at `Slot00_Size8`, the Type-7
+     * Transporter uses the number `09` twice, and the Keelback's `Slot03_Size3` sits
+     * on a size-**4** mount. Such a mount carries its own `name`; see
+     * {@link enumerateSlots}.
+     */
+    readonly key: string;
+    /**
+     * Slot size (class). Core/optional/hardpoint slots are 1–8; utility and armour
+     * use `0` placeholders because their fit rules are not size-based, while the
+     * fixed cargo hatch uses `1`.
+     */
+    readonly size: number;
+}
+/** A core-internal mount, which always names the one module function it accepts. */
+interface CoreBuildSlot extends BuildSlotBase {
+    /** Discriminator for a core-internal mount. */
+    readonly kind: 'core';
+    /** The core module function this mount accepts. */
+    readonly core: CoreSlotType;
+    /** Core mounts are never family-restricted. */
+    readonly restriction?: never;
+}
+/** A weapon hardpoint, optionally restricted to a weapon family. */
+interface HardpointBuildSlot extends BuildSlotBase {
+    /** Discriminator for a weapon hardpoint. */
+    readonly kind: 'hardpoint';
+    /** The weapon family this hardpoint requires, when restricted. */
+    readonly restriction?: HardpointRestriction;
+    /** Hardpoints never name a core module function. */
+    readonly core?: never;
+}
+/** An optional-internal mount, optionally restricted to a module family. */
+interface OptionalBuildSlot extends BuildSlotBase {
+    /** Discriminator for an optional-internal mount. */
+    readonly kind: 'optional';
+    /** The module family this optional mount requires, when restricted. */
+    readonly restriction?: OptionalRestriction;
+    /** Optional internals never name a core module function. */
+    readonly core?: never;
+}
+/** A utility, armour, or cargo-hatch mount with no kind-specific fields. */
+interface SimpleBuildSlot extends BuildSlotBase {
+    /** The exact simple mount kind. */
+    readonly kind: 'utility' | 'armour' | 'cargoHatch';
+    /** These mounts are never family-restricted. */
+    readonly restriction?: never;
+    /** These mounts never name a core module function. */
+    readonly core?: never;
+}
+/**
+ * One mount on a hull — its stable key, kind-specific fields, and size.
+ *
+ * Checking `kind` narrows `core` and `restriction`: core mounts always name their
+ * {@link CoreSlotType}; hardpoint and optional restrictions cannot be mixed; utility,
+ * armour, and cargo-hatch mounts carry neither field.
+ *
+ * @example
+ * ```ts
+ * import { getShipSlots } from '@elite-dangerous-almanac/core/ships/ships';
+ * import { enumerateSlots } from '@elite-dangerous-almanac/core/ships/slots';
+ *
+ * const slot = enumerateSlots(getShipSlots('Anaconda')!)[0]!;
+ * if (slot.kind === 'hardpoint') {
+ *   slot.restriction; // HardpointRestriction | undefined
+ * }
+ * ```
+ */
+type BuildSlot = CoreBuildSlot | HardpointBuildSlot | OptionalBuildSlot | SimpleBuildSlot;
+/**
+ * The size of each of a hull's seven core-internal mounts.
+ *
+ * @remarks
+ * Each value is the mount's class (size), `1`–`8`: the largest module that fits it.
+ * Keys are the core *functions* ({@link CoreSlotType}), not journal slot keys.
+ */
+interface CoreSlots {
+    /** Power-plant mount size, 1–8. */
+    readonly powerPlant: number;
+    /** Thruster mount size, 1–8 (journal slot `MainEngines`). */
+    readonly thrusters: number;
+    /** Frame shift drive mount size, 1–8. */
+    readonly frameShiftDrive: number;
+    /** Life-support mount size, 1–8. */
+    readonly lifeSupport: number;
+    /** Power-distributor mount size, 1–8. */
+    readonly powerDistributor: number;
+    /** Sensor mount size, 1–8 (journal slot `Radar`). */
+    readonly sensors: number;
+    /** Main fuel-tank mount size, 1–8. */
+    readonly fuelTank: number;
+}
+/** One weapon hardpoint in a hull's layout. */
+interface HardpointSlotSpec {
+    /** Mount size (class), `1` Small – `4` Huge. */
+    readonly size: number;
+    /**
+     * A restriction, if this mount only takes one family of weapons. Only the
+     * Type-11 Prospector has any; see {@link HardpointRestriction}.
+     */
+    readonly restriction?: HardpointRestriction;
+    /**
+     * The mount's own journal slot key, when the numbering rules do not reproduce it
+     * — the Type-8 Transporter's `SmallHardpoint4`, the Caspian Explorer's
+     * out-of-order mediums. Absent when the rules are right; see
+     * {@link enumerateSlots} for which hulls carry names and why.
+     */
+    readonly name?: string;
+}
+/** One optional-internal mount in a hull's layout. */
+interface OptionalSlotSpec {
+    /** Slot size (class), 1–8. */
+    readonly size: number;
+    /**
+     * A restriction, if this mount only takes one family of modules; see
+     * {@link OptionalRestriction}.
+     */
+    readonly restriction?: OptionalRestriction;
+    /**
+     * The mount's own journal slot key, when the numbering rules do not reproduce it
+     * — the Anaconda's `Slot14_Size1`, the Type-9 Heavy's `Slot00_Size8`, the
+     * Keelback's `Slot03_Size3`. Absent when the rules are right; see
+     * {@link enumerateSlots} for which hulls carry names and why.
+     *
+     * @remarks
+     * **The `_SizeN` in the key may disagree with {@link OptionalSlotSpec.size}**,
+     * which is always the mount's real class — the Keelback's `Slot03_Size3` names a
+     * size-4 mount. That is Frontier's own text, kept verbatim.
+     */
+    readonly name?: string;
+}
+/**
+ * A hull's full slot layout — the slot-bearing fields of a `Ship`, as `getShipSlots`
+ * returns.
+ *
+ * @remarks
+ * The armour mount is not listed here because it is not sized: a hull's armour options
+ * are ordinary modules in `CORE_MODULES`, tied to the hull by their
+ * {@link OutfittingModule.ship} field. List them with `getBulkheadsForShip`.
+ */
+interface ShipSlots {
+    /** Hull symbol, matching the registry's `Ship.symbol`. */
+    readonly symbol: string;
+    /** The seven core-internal sizes. */
+    readonly core: CoreSlots;
+    /** Weapon hardpoints, largest first. */
+    readonly hardpoints: readonly HardpointSlotSpec[];
+    /** Number of tiny utility mounts. */
+    readonly utility: number;
+    /** Optional-internal mounts, largest first. */
+    readonly optional: readonly OptionalSlotSpec[];
+}
+/** What a journal slot key says about the mount, as {@link parseSlotName} reads it. */
+interface ParsedSlot {
+    /** Which kind of mount the key names. */
+    readonly kind: SlotKind;
+    /**
+     * Slot size (class), 1–8, or `null` when the key does not encode one and the mount
+     * has one to encode (`Radar`, `Military01`, `Cargo01`, …) — the hull's layout
+     * carries the size instead.
+     *
+     * @remarks
+     * `null` is not the only "no size here" answer. A mount whose fit rules are not
+     * size-based reads `0` rather than `null` — `TinyHardpoint1` and `Armour` both do,
+     * matching the `size` on a {@link BuildSlot} — and `CargoHatch` reads `1`. So test
+     * `parsed.size` for falsiness, or against the {@link ParsedSlot.kind} you expect;
+     * `=== null` alone treats a utility mount as a sized slot.
+     */
+    readonly size: number | null;
+    /**
+     * The restriction the key implies (`Military01` → `military`,
+     * `LargeMiningHardpoint1` → `mining`). Frontier gives every restricted mount its
+     * own journal name, so a key alone is enough to tell.
+     */
+    readonly restriction?: SlotRestriction;
+    /** For a core key, the core function it fills (`MainEngines` → `thrusters`). */
+    readonly core?: CoreSlotType;
+}
+/**
+ * Expand a hull's {@link ShipSlots} layout into keyed {@link BuildSlot}s, in
+ * outfitting-panel order: hardpoints, utility mounts, armour, the seven core
+ * internals, then the optional internals, then the cargo hatch.
+ *
+ * The keys are journal-compatible, so the same key identifies a mount whether the
+ * build was assembled from scratch or loaded from a SLEF export — SLEF being the
+ * journal's own `Loadout` event in an envelope, its `Slot` strings are these.
+ *
+ * @param layout - The hull's slot layout.
+ * @returns Every mount the hull offers, as {@link BuildSlot}s.
+ * @remarks
+ * Unrestricted optionals are numbered `Slot01_SizeN`, `Slot02_SizeN`, … with no gaps,
+ * and hardpoints `1, 2, 3` within each size class. **Ten hulls disagree**, and no
+ * rule derives what they do instead, so a mount on one of them carries its own
+ * {@link OptionalSlotSpec.name} / {@link HardpointSlotSpec.name} and that wins:
+ *
+ * | Hull | What the game names it |
+ * | --- | --- |
+ * | Anaconda | `Slot13_Size2`, `Slot14_Size1` — no 11 or 12 |
+ * | Type-9 Heavy | starts at `Slot00_Size8`; then jumps `Slot08` → `Slot11` |
+ * | Type-10 Defender, Federal Dropship, Vulture | a gap before the last mounts |
+ * | Type-7 Transporter | the number `09` twice, and five suffixes misreport the size |
+ * | Keelback, Asp Scout | one suffix misreports the size |
+ * | Type-8 Transporter | `SmallHardpoint2` then `SmallHardpoint4` |
+ * | Caspian Explorer | mediums run `6, 5, 1, 2, 3, 4` — out of order, not just gapped |
+ *
+ * The Panther Clipper Mk II, Type-11 Prospector and Lynx Highliner also carry explicit
+ * names that match the derived keys. The Lynx's `Slot02_Size5` follows three
+ * `PassengerNN` mounts because a restricted `passenger` mount consumes no `SlotNN`
+ * number.
+ * A hull that names any mount of a kind names all of them, so a derived key and a name
+ * never compete for the same string.
+ * @example
+ * ```ts
+ * import { getShipSlots } from '@elite-dangerous-almanac/core/ships/ships';
+ * import { enumerateSlots } from '@elite-dangerous-almanac/core/ships/slots';
+ *
+ * enumerateSlots(getShipSlots('Anaconda')!).filter((s) => s.kind === 'hardpoint');
+ * // -> [{ key: 'HugeHardpoint1', size: 4, ... }, { key: 'LargeHardpoint1', size: 3, ... }, ...]
+ * enumerateSlots(getShipSlots('Anaconda')!)
+ *     .filter((s) => s.kind === 'optional' && !s.restriction)
+ *     .at(-1)?.key; // -> 'Slot14_Size1', not 'Slot12_Size1'
+ * ```
+ */
+declare function enumerateSlots(layout: ShipSlots): BuildSlot[];
+/**
+ * Classify a journal slot name — the `Slot` field of a SLEF/journal module — into a
+ * {@link ParsedSlot}.
+ *
+ * @param slot - The journal slot name, e.g. `"FrameShiftDrive"`, `"MediumHardpoint2"`,
+ * `"Slot03_Size5"`, `"Military01"`, `"LargeMiningHardpoint1"`. Matched
+ * **case-insensitively** — see the remarks.
+ * @returns The classification, or `null` if the name is not a recognised slot. `size`
+ * is `null` for names that do not encode a size (a bare `Military01`).
+ * @remarks
+ * Every restricted mount has a journal name of its own, so the restriction is read
+ * off the name and needs no hull layout. The size still may: `Cargo01` says only
+ * that the mount takes cargo, and `getShipSlots` carries how big it is.
+ *
+ * **Casing is not significant.** Frontier writes `FrameShiftDrive`, but a SLEF
+ * producer may lower-case every slot key as the specification's own example does —
+ * Inara writes `powerplant` and `largemininghardpoint1` — and both name the same
+ * mount. The returned `core` and `restriction` values keep this library's own
+ * camelCase spelling whatever the input looked like.
+ *
+ * **A `_SizeN` suffix is what the name says, not what the mount is.** On three hulls
+ * the game's own key disagrees with the mount it names — the Keelback's
+ * `Slot03_Size3` is a size-4 mount, the Asp Scout's `Slot01_Size4` a size-5 one, and
+ * five of the Type-7 Transporter's ten are off. To size a mount, find it in the hull's
+ * layout ({@link enumerateSlots}) rather than trusting the number returned here.
+ * @throws {TypeError} If `slot` is present and not a string. A nullish `slot` is a miss,
+ * answered the way an unrecognised key is.
+ * @example
+ * ```ts
+ * import { parseSlotName } from '@elite-dangerous-almanac/core/ships/slots';
+ *
+ * parseSlotName('Slot03_Size5'); // -> { kind: 'optional', size: 5 }
+ * parseSlotName('HugeHardpoint1'); // -> { kind: 'hardpoint', size: 4 }
+ * parseSlotName('LargeMiningHardpoint1');
+ * // -> { kind: 'hardpoint', size: 3, restriction: 'mining' }
+ * parseSlotName('Radar'); // -> { kind: 'core', size: null, core: 'sensors' }
+ * parseSlotName('powerplant'); // -> { kind: 'core', size: null, core: 'powerPlant' }
+ * ```
+ */
+declare function parseSlotName(slot: string): ParsedSlot | null;
+
+export { type BuildSlot, type BuildSlotBase, type CoreBuildSlot, type CoreSlotType, type CoreSlots, type HardpointBuildSlot, type HardpointRestriction, type HardpointSlotSpec, type ModuleSlot, type OptionalBuildSlot, type OptionalRestriction, type OptionalSlotSpec, type ParsedSlot, SLOT_RESTRICTION_LABELS, type ShipSlots, type SimpleBuildSlot, type SlotKind, type SlotRestriction, enumerateSlots, parseSlotName };

package/dist/ships/slots.js

@@ -0,0 +1 @@
+export{SLOT_RESTRICTION_LABELS,enumerateSlots,parseSlotName}from"../chunk-I7PIDRMU.js";                                                          //# sourceMappingURL=slots.js.map

package/dist/ships/slots.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"O"}

package/dist/ships/source-purchase.d.ts

@@ -0,0 +1,132 @@
+import { LoadoutEvent } from './slef.js';
+
+/**
+ * Frozen purchase snapshots and pure queries for credit figures carried by a journal
+ * `Loadout` event or SLEF export.
+ *
+ * A capture preserves figures from one commander's purchase history. They can combine
+ * station discounts, omit bought modules, and disagree with their own totals, so they
+ * remain separate from the catalogue-retail figures calculated for a live build.
+ *
+ * @packageDocumentation
+ */
+
+/** One slot's captured purchase price, exactly as the source stated it. */
+interface SourceModuleValue {
+    /** The slot key, in the source's own spelling. */
+    readonly slot: string;
+    /** The module symbol, in the source's own casing. */
+    readonly item: string;
+    /** What the source says was paid for that module, in credits. */
+    readonly value: number;
+}
+/**
+ * An immutable snapshot of the credit figures carried by one captured loadout.
+ *
+ * Every top-level figure can be `null`: absence means the source stated no value, not
+ * that the hull or modules were free. Likewise, {@link moduleValues} contains only
+ * individually priced slots. The snapshot remains unchanged when its owning
+ * {@link ShipLoadout} is edited because it describes the source capture, not the live
+ * fit.
+ *
+ * @example
+ * ```ts
+ * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+ * import {
+ *     getSourceModuleValue,
+ *     sumSourceModuleValues,
+ * } from '@elite-dangerous-almanac/core/ships/source-purchase';
+ *
+ * declare const slefJson: string;
+ *
+ * const build = ShipLoadout.fromSlef(slefJson);
+ * const paid = build.sourcePurchase;
+ * if (paid) {
+ *     paid.hullValue; // captured hull price, or null
+ *     getSourceModuleValue(paid, 'PowerPlant')?.value; // captured slot price
+ *     sumSourceModuleValues(paid); // sum of individually priced modules
+ * }
+ * ```
+ */
+interface SourcePurchaseRecord {
+    /** Hull cost in credits as the source stated it, or `null` if it stated none. */
+    readonly hullValue: number | null;
+    /** Fitted-module cost in credits as the source stated it, or `null` if absent. */
+    readonly modulesValue: number | null;
+    /** Insurance rebuy in credits as the source stated it, or `null` if absent. */
+    readonly rebuy: number | null;
+    /** Individually priced slots, in capture order; unpriced slots are absent. */
+    readonly moduleValues: readonly SourceModuleValue[];
+    /** Total modules listed by the capture, including entries with no price. */
+    readonly moduleCount: number;
+}
+/**
+ * Capture the purchase figures from a journal `Loadout` event or SLEF data object.
+ *
+ * @param event - Source event to snapshot. No object in it is retained by reference.
+ * @returns A deeply frozen record, or `null` when the source states no credit figure at
+ * all.
+ * @remarks
+ * A malformed event that repeats an exactly spelled slot keeps the last entry.
+ * {@link ShipLoadout.fromLoadout} independently rejects duplicate mounts before
+ * constructing a usable build.
+ *
+ * No discount is inferred. One capture can mix purchases from several stations, omit
+ * module values, or state a total that differs from its priced parts. The snapshot keeps
+ * those facts visible instead of inventing one misleading percentage.
+ * @example
+ * ```ts
+ * import type { LoadoutEvent } from '@elite-dangerous-almanac/core/ships/slef';
+ * import { sourcePurchaseFromLoadout } from '@elite-dangerous-almanac/core/ships/source-purchase';
+ *
+ * declare const event: LoadoutEvent;
+ * const paid = sourcePurchaseFromLoadout(event);
+ * paid?.rebuy; // captured rebuy, or null
+ * ```
+ */
+declare function sourcePurchaseFromLoadout(event: LoadoutEvent): SourcePurchaseRecord | null;
+/**
+ * Find the captured purchase entry for one slot.
+ *
+ * @param record - Purchase snapshot to query.
+ * @param slotKey - Slot key such as `"PowerPlant"`. An exact spelling wins; otherwise
+ * matching is case-insensitive so journal and lower-cased SLEF keys interoperate.
+ * @returns The frozen entry, or `null` when the source priced no module in that slot.
+ * `null` never means the module was free.
+ * @throws {TypeError} If `slotKey` is present and not a string. A nullish `slotKey` is a
+ * miss, answered the way a slot the source did not price is.
+ * @example
+ * ```ts
+ * import {
+ *     getSourceModuleValue,
+ *     type SourcePurchaseRecord,
+ * } from '@elite-dangerous-almanac/core/ships/source-purchase';
+ *
+ * declare const paid: SourcePurchaseRecord;
+ * getSourceModuleValue(paid, 'FrameShiftDrive')?.value; // captured credits
+ * ```
+ */
+declare function getSourceModuleValue(record: SourcePurchaseRecord, slotKey: string): SourceModuleValue | null;
+/**
+ * Sum every per-slot price that the source stated.
+ *
+ * @param record - Purchase snapshot whose individually priced entries to add.
+ * @returns The stated total in credits, or `0` when no module was individually priced.
+ * @remarks
+ * This is deliberately not a replacement for {@link SourcePurchaseRecord.modulesValue}.
+ * A capture may omit individual prices or publish an inconsistent total; comparing the
+ * two is useful precisely because this function does not hide that discrepancy.
+ * @example
+ * ```ts
+ * import {
+ *     sumSourceModuleValues,
+ *     type SourcePurchaseRecord,
+ * } from '@elite-dangerous-almanac/core/ships/source-purchase';
+ *
+ * declare const paid: SourcePurchaseRecord;
+ * const partsAgree = paid.modulesValue === sumSourceModuleValues(paid);
+ * ```
+ */
+declare function sumSourceModuleValues(record: SourcePurchaseRecord): number;
+
+export { type SourceModuleValue, type SourcePurchaseRecord, getSourceModuleValue, sourcePurchaseFromLoadout, sumSourceModuleValues };

package/dist/ships/source-purchase.js

@@ -0,0 +1 @@
+export{getSourceModuleValue,sourcePurchaseFromLoadout,sumSourceModuleValues}from"../chunk-QTDBO7R2.js";                                                          //# sourceMappingURL=source-purchase.js.map

package/dist/ships/source-purchase.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"O"}