@loontail/minecraft-kit v0.8.14

Classes

Class	Description
ChildProcessSpawner	Default spawner backed by node:child_process.spawn.
FabricVersionsApi	Public Fabric versions API surface.
FetchHttpClient	Default HttpClient implementation backed by Node's built-in fetch (undici under the hood). Maps fetch errors to MinecraftKitError.
ForgeVersionsApi	Public Forge versions API surface.
MinecraftKit	Single facade for the entire library.
MinecraftKitError	The single error class thrown by every public API in @loontail/minecraft-kit.
MinecraftVersionsApi	Public Minecraft versions API surface.
MojangAuthApi	High-level Microsoft / Mojang auth surface attached to MinecraftKit as kit.auth. Sign-in uses the OAuth 2.0 Authorization Code + PKCE flow with a loopback redirect (kit.auth.authorizationCode): the kit opens a localhost server, the caller opens the system browser, the user signs in, and the browser redirects back. The flow continues through the Xbox → XSTS → Minecraft pipeline and returns a MojangSession carrying everything launch composition needs plus the Microsoft refresh token. The library does NOT persist tokens — that's the caller's job.
PauseController	Cooperative pause primitive. Consumers call waitWhilePaused at safe checkpoints. Independent from AbortSignal — abort wins at the next signal check.
RuntimeVersionsApi	Public runtime versions API surface.
TargetsApi	Public Targets API surface.

Type Aliases

Type alias	Description
Architecture	Architecture literal used in launcher metadata.
ArgumentEntry	A single argument entry: bare string or rule-gated value.
ArtifactDownload	A single hash-verified download.
AspectRepairInput	Inputs accepted by every aspect-specific planXxxRepair (planMinecraftRepair, planFabricRepair, planForgeRepair, planRuntimeRepair). The per-aspect input types are aliases over this shape.
AssetIndexReference	Reference to the asset-index JSON file.
AuthMode	Auth mode literal.
AuthorizationCodeRunOptions	Options accepted by kit.auth.authorizationCode.run.
AzureClientId	Branded Azure AD application id. Construct via asAzureClientId (exported from the package root) — the brand prevents accidentally passing a refresh token or a UUID where the kit expects a client id.
DetectSystemInput	Inputs allowing the host system to be derived from current Node values or overrides.
DiscoveredLoaderHint	Inferred loader hint (does not assert correctness).
DiscoveredRuntimeHint	Detected runtime files.
DiscoveredTarget	Discovered installation found by scanning a root directory. Contains only what was actually read from disk — no assumptions about correctness, completeness, or repair state.
DownloadAction	A single download step.
DownloadCategory	Download category literal — drives runInstall phase boundaries.
EventType	Literal type of the type discriminator of a ProgressEvent.
ExtractNativeAction	A native extraction step. Source jar must already exist on disk.
FabricGameVersionEntry	One entry from the upstream Fabric gameVersions listing — the set of Minecraft versions Fabric supports at all, independent of any specific loader version.
FabricGameVersionsInput	Inputs to FabricVersionsApi.gameVersions.
FabricListInput	Inputs to FabricVersionsApi.list.
FabricLoaderSummary	Summary entry from /v2/versions/loader.
FabricProfile	Fabric profile JSON returned by /v2/versions/loader/{mc}/{loader}/profile/json.
FabricResolveInput	Inputs to FabricVersionsApi.resolve.
FileRef	Reference to a single file used in download events.
ForgeBuildSummary	A Forge build entry derived from the Maven metadata XML.
ForgeListInput	Inputs to ForgeVersionsApi.list.
ForgeResolveInput	Inputs to ForgeVersionsApi.resolve.
HttpClient	Pluggable HTTP client. The default implementation uses Node's built-in fetch; consumers can inject a fake (e.g. for tests) by passing an httpClient to the MinecraftKit constructor.
HttpHeaders	Subset of fetch headers the library actually uses.
HttpMethod	HTTP method supported by HttpClient.
HttpRequestBody	Body payload accepted on POST requests.
HttpRequestOptions	Options for an HTTP request.
HttpResponse	Response delivered by the HttpClient interface.
InstallAction	Discriminated union of install actions.
InstallActionKind	Discriminator for an install action.
InstallAspect	Shape of kit.install. Consumers usually access this through kit.install; the alias is exported so the facade documentation can show the concrete surface.
InstallPhase	Install phase literal.
InstallPlan	Pre-computed install plan: a flat ordered list of actions plus computed totals.
InstallPlanTarget	Shape of InstallPlan.target. Either a fully-resolved Target (from ./target) or a runtime-only stand-in. The install runner only reads target.minecraft/target.loader when the plan actually contains those steps, so runtime-only plans are safe.
InstallProgressTracker	Aggregator returned by createInstallProgressTracker. Wire onEvent into install.run / repair.run, and subscribe into your UI layer.
InstallReport	Outcome summary returned by install.run.
InstallRunOptions	Options accepted by install.run (and install.runtime.run).
LaunchAspect	Shape of kit.launch.
LaunchAuth	Auth shape consumed by kit.launch.compose. Either an OfflineAuth or OnlineAuth.
LaunchComposition	Fully composed launch command, ready to be passed to kit.launch.run.
LaunchExit	Outcome of a finished launch.
LaunchMemoryOptions	Optional memory configuration.
LaunchOptions	Inputs for kit.launch.compose (and the lower-level composeLaunch helper).
LaunchPreflightResult	Result of a network-free kit.launch.preflight(target) check.
LaunchResolutionOptions	Optional resolution / window configuration.
LaunchRunOptions	Options for kit.launch.run (and the lower-level runLaunch helper).
LaunchSession	Live handle for a running game process.
LibraryArtifact	An individual library artifact (jar/zip).
LibraryRule	Rule entry used by libraries and modern arguments.
Loader	A fully resolved loader pinned to a specific Minecraft version. Use the type field to narrow to the concrete shape.
LoaderKind	Loader-kind literal (used as discriminator on loader objects).
LogLevel	Log-level literal.
Logger	Pluggable logger. Default implementation is a silent logger; pass your own to surface logs.
MemoryCacheOptions	Inputs to createMemoryCache.
MetadataCache	Pluggable in-memory cache for HTTP metadata responses. Default implementation: createMemoryCache. Implement this to back the cache by Redis, disk, etc.
MicrosoftRefreshToken	Branded Microsoft refresh token. Construct via asMicrosoftRefreshToken (exported from the package root) — the brand prevents accidentally passing an access token, XSTS token, or another opaque string where a Microsoft refresh token is expected.
MinecraftArguments	Modern (1.13+) arguments structure.
MinecraftChannel	Channel literal as it appears in version manifest entries.
MinecraftDownloads	Per-platform downloads block of the Minecraft per-version manifest.
MinecraftGetInput	Inputs to MinecraftVersionsApi.get / .resolve.
MinecraftJavaVersion	Required Java runtime descriptor from the version manifest.
MinecraftKitErrorCode	Union of every value in MinecraftKitErrorCodes. Use as the key type when building exhaustive lookup tables that translate kit codes to a consumer-facing taxonomy.
MinecraftKitErrorContext	Structured context attached to errors. Always safe to serialize via JSON.stringify.
MinecraftKitOptions	Constructor options for MinecraftKit.
MinecraftLatestInput	Inputs to MinecraftVersionsApi.latest.
MinecraftLibrary	Library entry. Combines vanilla, modern-natives, and legacy-classifier shapes.
MinecraftLibraryDownloads	Library downloads block.
MinecraftListInput	Inputs to MinecraftVersionsApi.list.
MinecraftLogging	Logging-config entry from the version manifest.
MinecraftProfile	Snapshot of /minecraft/profile — uuid + display name + every skin slot Mojang has issued. Returned by every kit.auth.profile.* mutation so callers can refresh their UI without an extra round-trip.
MinecraftVersionId	Branded Minecraft version id (e.g. "1.20.1", "1.20.1-forge-47.2.0", "fabric-loader-0.14.21-1.20.1"). Construct via asMinecraftVersionId (exported from the package root) — the brand prevents accidentally passing a player UUID, an asset-index id, or another opaque string where the install/launch pipeline expects a Minecraft version id.
MinecraftVersionManifest	Subset of the per-version manifest used by resolvers and consumers.
MinecraftVersionSummary	One entry from the top-level Minecraft version_manifest_v2.json listing.
MojangAssetState	-
MojangProfileSkin	A single skin slot returned by /minecraft/profile.
MojangSession	Combined Microsoft + Minecraft session returned by kit.auth.authorizationCode.run and kit.auth.refresh.
OfflineAuth	Offline authentication.
OnlineAuth	Online (token-based) authentication.
OperatingSystem	OS literal as used inside Mojang/Forge/Fabric JSON manifests.
OperationOptions	Common options accepted by long-running operations.
PersistentMetadataCache	Disk-backed MetadataCache plus a PersistentMetadataCache.flush hook for awaiting in-flight writes (e.g. on app quit, or in tests).
PersistentMetadataCacheOptions	Options for createPersistentMetadataCache.
PlanStandaloneRuntimeInstallInput	Inputs to planStandaloneRuntimeInstall.
PlayerUuid	Branded Minecraft player UUID. Construct via asPlayerUuid (exported from the package root) — the brand prevents accidentally passing a Minecraft version id, an Xbox userhash, or another opaque string where the launch composer expects a player UUID.
ProcessStream	Stream-of-text channel exposed by spawned processes.
ProcessorRef	A single processor description used in Forge events.
ProgressEvent	Discriminated union of all runtime progress events. Pass an onEvent callback to install.run, update.run, verify.run, repair.run, or launch.run to receive these.
ProgressEventContext	Optional aspect metadata attached by verification and aggregate repair flows.
ProgressListener	Listener signature accepted by every long-running operation.
ProgressSnapshot	Snapshot pushed to InstallProgressTracker subscribers.
ProgressStage	Literal type of ProgressStages. Use for exhaustive switches in UI code.
ProgressTrackerOptions	Options for createInstallProgressTracker.
ReadProfileInput	Inputs to readProfile.
RefreshOptions	Options accepted by kit.auth.refresh.
RepairAllOptions	Options for kit.repair.all. Extends the common long-running operation options with caller-owned issue filtering.
RepairAllReport	Result of repairAll: every verification it ran, every repair it performed, every aspect a connectivity failure blocked, and the aggregate cost.
RepairAspect	Shared shape of every aspect-specific repair surface (repair.minecraft, .fabric, …).
RepairBlockedAspect	Why an aspect could not be repaired this run. Recorded by repairAll when planning or running a repair fails with a connectivity error, so an offline "Repair" degrades to "these aspects still need the network" instead of rejecting the whole operation.
RepairFromErrorInput	Inputs to kit.repair.fromError({ error, target }). Resume a failed install by deriving the smallest possible RepairPlan from a typed MinecraftKitError thrown by a previous kit.install.run (or any other operation that surfaces the same codes).
RepairIssueFilter	Predicate used by repair planning to decide whether a verification issue belongs to the kit-managed repair plan. Return false for files intentionally owned by the caller.
RepairIssueFilterInput	Context passed to caller-owned repair filters.
RepairMode	Repair-mode literal accepted by kit.repair.runVerifyAndRepair.
RepairPhase	Repair phase literal.
RepairPlan	A repair plan is, structurally, an install plan limited to actions needed to fix the issues reported by a previous VerificationResult. The runner is the same.
RepairPlanOptions	Options for any repair.<aspect>.plan call. Accepts one or many verification results.
RepairReport	Repair report — same shape as install report.
RepairSurface	Shape of kit.repair. Four aspect-specific surfaces plus the all convenience that verifies every applicable slice and repairs each broken one, and fromError which resumes a failed install by deriving a focused plan from a typed MinecraftKitError.
RepairableErrorLike	Structural shape of the MinecraftKitError passed to RepairFromErrorInput. Defined here so src/types/ does not need to import the error class from src/core/. Any thrown MinecraftKitError satisfies this shape.
ResetSkinInput	Inputs to resetSkin.
ResolvedFabricLoader	Resolved Fabric loader for a specific Minecraft version.
ResolvedForgeLoader	Resolved Forge loader.
ResolvedLaunchVersion	Result of resolving the on-disk version JSON for a target.
ResolvedMinecraft	Fully resolved Minecraft version: summary + parsed manifest, ready to feed into kit.targets.create or kit.install.plan.
ResolvedRuntime	Resolved runtime ready to install or launch with.
ResolvedVanillaLoader	Trivial loader used when no mod loader is in play. Carries the resolved Minecraft so the launch composer has a uniform view across vanilla / Fabric / Forge.
RunForgeProcessorAction	A Forge processor invocation. Main-Class is intentionally NOT carried here — the runner reads it from classpath[0]'s manifest at execution time, because the JAR is not guaranteed to exist on disk during planning (newer Forge versions ship some processor JARs as regular Maven libraries instead of bundling them in the installer).
RunVerifyAndRepairDeps	Dependencies for the standalone runVerifyAndRepair helper.
RuntimeComponent	Runtime component literal. Always a string; the RuntimeComponents const lists the components we know about but unknown ones (added by Mojang in the future) are resolved dynamically.
RuntimeListEntry	A summary entry for the list API.
RuntimeListInput	Inputs to RuntimeVersionsApi.list.
RuntimeOnlyInstallTarget	A "runtime-only" install plan target. Used by planStandaloneRuntimeInstall to plan a JRE-only install without a Minecraft version/loader pinned to the plan.
RuntimePreferenceKind	Runtime preference literal.
RuntimeResolveInput	Inputs to RuntimeVersionsApi.resolve.
RuntimeSystem	Identifies the host system for the launcher. All resolvers consume this object to pick the right artifacts (libraries, natives, runtime).
SetSkinFromUrlInput	Inputs to setSkinFromUrl.
SkinVariant	-
SkinVariantInput	-
SpawnOptions	Options accepted by the spawner.
SpawnedProcess	Live handle for a child process.
Spawner	Pluggable process spawner. The default implementation uses node:child_process; tests inject a fake to avoid spawning real processes.
Target	Fully resolved target: a concrete Minecraft + loader + runtime + directory.
TargetCreateInput	Inputs accepted by kit.targets.create.
TargetListInput	Inputs to TargetsApi.list.
TargetLoaderInput	Loader input variants.
TargetReadinessIssue	A verification issue annotated with the aspect that produced it.
TargetReadinessResult	Aggregate launch-readiness report for every aspect that applies to a target.
TargetResolveInput	Inputs to TargetsApi.resolve.
TargetsApiContext	Constructor inputs for TargetsApi.
UploadSkinInput	Inputs to uploadSkin.
VerificationFileResult	A single verified file.
VerificationKind	Verification kind literal.
VerificationResult	Aggregate verification result returned by each verify.<kind>.run API.
VerifyAndRepairInput	Inputs to kit.repair.runVerifyAndRepair({ aspect, target, mode? }). Runs a single aspect's verifier and, in 'fix' mode, plans + executes the repair for any issues it finds. In 'report' mode the function never writes to disk.
VerifyAndRepairResult	Result of kit.repair.runVerifyAndRepair. verified is always the verification result; repair is the repair report when a fix ran, or null when nothing needed fixing or mode === RepairModes.REPORT.
VerifyAspect	Shape of kit.verify. The four per-aspect surfaces share the same (target, options) → Promise<VerificationResult> contract; targetReady aggregates them for launch gating.
VerifyFileCategory	Verification file category literal.
VerifyFileStatus	File status literal.
VerifyOperationOptions	Options accepted by every verify.<kind>.run.
VersionPreferenceKind	Resolution-preference literal.
WriteLoggingConfigAction	Write a logging config (log4j XML) to disk.
WriteVersionJsonAction	Write a version JSON to disk (Fabric / Forge).

Variables

Variable	Description
Architectures	CPU architecture identifiers. Matches the values that appear in Mojang library os.arch fields, after normalization from Node's NodeJS.Architecture.
AuthModes	Authentication modes accepted by the launch composer.
CLIENT_ID_ENV_VAR	Env var consulted when no explicit clientId is supplied.
DownloadCategories	Categorisation tag on every DownloadAction. Drives the install-phase mapping and lets consumers filter the plan to a subset (e.g. "runtime only").
EventTypes	Stable string constants for the type discriminator of every ProgressEvent. Use these instead of bare string literals when filtering events.
InstallActionKinds	Action kinds inside an InstallPlan.
InstallPhases	Coarse-grained install phases. Used in install:phase-changed events so consumers can render a progress bar with named steps.
Loaders	Discriminator literal identifying which mod loader is active for a target.
LogLevels	Log levels accepted by the pluggable logger.
MinecraftChannels	Minecraft release channels matching the type field of Mojang version manifest entries.
MinecraftKitErrorCodes	Stable error code registry. MinecraftKitError carries one of these as code; consumers can switch on it exhaustively via the derived MinecraftKitErrorCode union.
MojangAssetStates	Lifecycle state of a Mojang-issued skin slot.
OperatingSystems	Operating-system identifiers used by Mojang launcher metadata.
ProgressStages	UI-oriented coarse progress stages, identical across install and repair flows.
RepairModes	Modes accepted by kit.repair.runVerifyAndRepair.
RepairPhases	Coarse-grained repair phases used for repair:phase-changed events.
RuntimeComponents	Mojang Java-runtime component identifiers. New components appear over time (e.g. java-runtime-delta for Java 21).
RuntimePreference	User-supplied resolution preferences.
SkinVariantInputs	Skin-variant input that accepts "AUTO" in addition to the regular SkinVariant. "AUTO" triggers per-pixel detection by detectSkinVariant — useful when the caller does not know whether the user picked a Steve-style or Alex-style PNG.
SkinVariants	Skin model variant — "CLASSIC" for standard 4-pixel arms (Steve) or "SLIM" for 3-pixel arms (Alex).
VerificationKinds	Aspect of an installation a verification result describes.
VerifyFileCategories	Categories assigned to each verified file for easier filtering.
VerifyFileStatuses	Status of an individual file checked during verification.
VersionPreference	Resolution preference used when a user wants the latest, recommended, or a specific version. Preferences are inputs to resolvers; resolved targets always carry concrete versions.
consoleLogger	Logger that mirrors messages to console.<level> with structured fields.
silentLogger	Logger that drops every message. Default when no logger is supplied.
targetPaths	Helpers for the per-target Minecraft directory layout. Use these to derive paths to a specific file (versions/<id>/<id>.jar, assets/objects/<aa>/<sha1>, …) consistently with what the install and verify runners write/expect.

Functions

Function	Description
asAzureClientId	Validate raw as an Azure AD application id and brand it as AzureClientId. Throws MinecraftKitError(INVALID_INPUT) if the input is empty or does not match the GUID-ish shape Azure uses (hex characters and dashes, at least 8 characters).
asMicrosoftRefreshToken	Brand raw as a MicrosoftRefreshToken. Validates only that the value is non-empty after trimming — Microsoft refresh tokens are opaque, so the constructor's job is to put a brand on the value, not to second-guess Microsoft's format.
asMinecraftVersionId	Validate raw as a Minecraft version id and brand it as MinecraftVersionId. Throws MinecraftKitError(INVALID_INPUT) when the input is empty after trimming. Version ids span vanilla ("1.20.1"), snapshot ("24w14a"), and loader-flavoured shapes ("fabric-loader-0.14.21-1.20.1", "1.20.1-forge-47.2.0"), so the constructor only enforces non-emptiness — the resolver decides whether the id actually corresponds to a published version.
asPlayerUuid	Validate raw as a Minecraft player UUID and brand it as PlayerUuid. Throws MinecraftKitError(INVALID_INPUT) when the input is empty after trimming. The constructor does not enforce a specific UUID shape — Mojang accepts both dashed and undashed forms in different APIs — but it does reject the empty string so a missing storage entry can't quietly become a UUID-shaped placeholder.
assertNever	Exhaustiveness sentinel for discriminated unions. Drop into the default of a switch on kind / type / status so the compiler errors when a new variant is added but the switch is not updated.
createInstallProgressTracker	Aggregate ProgressEvents from one install/repair run into throttled UI snapshots.
createMemoryCache	In-memory metadata cache backed by lru-cache. Suitable for short-lived processes; pass a custom MetadataCache to share entries across runs (Redis, disk, etc.).
createPersistentMetadataCache	Create a MetadataCache that survives process restarts. Resolved version manifests, asset indexes, and runtime indexes written during one launch are still readable on the next — so a target resolved while online resolves offline later without the per-endpoint 30s network stall. This is the kit side of the launcher's fully-offline status seed (launcher optimization-13).
detectSkinVariant	Inspect the raw PNG bytes of a Minecraft skin and decide whether it follows the 4-pixel-wide arm ("CLASSIC" / Steve) or 3-pixel-wide arm ("SLIM" / Alex) model.
detectSystem	Resolve the current host system identifiers.
isErrorCode	True when e is an MinecraftKitError carrying the given MinecraftKitErrorCode.
isMinecraftKitError	True when e is an MinecraftKitError.
offlineUuidFor	Derive a stable v3-style UUID for an offline player username.
planFabricRepair	Build a repair plan covering the Fabric loader slice: profile JSON + libraries.
planForgeRepair	Build a repair plan covering the Forge loader slice: version JSON, libraries, installer download, and the Forge processors that produce the final installation. When the Forge version JSON was missing during verify (so libraries couldn't be enumerated), every forge-library download is added defensively — downloadFile skips files already on disk.
planMinecraftRepair	Build a repair plan covering only the vanilla Minecraft slice: client jar, version JSON, libraries (incl. native jars), assets, logging config, and native extractions.
planRuntimeInstall	Build an install plan that downloads ONLY the Java runtime declared by target.runtime.
planRuntimeRepair	Build a repair plan covering the Java runtime files. target.runtime.installRoot is honoured automatically because both planInstall and the verify side resolve runtime paths through the same targetPaths.runtimeRoot(..., installRoot) helper.
planStandaloneRuntimeInstall	Plan a runtime-only install without a Minecraft target. Useful for "Install Java/runtime" flows where the user just wants a JRE on disk and never had a Minecraft version to choose from. The returned plan is shaped exactly like a normal InstallPlan but uses a RuntimeOnlyInstallTarget that carries only the runtime + directory — the runner skips Minecraft/loader-specific stages because they have no actions in this plan.
repairAll	Verify every applicable aspect and repair each broken one. Aspects whose repair cannot reach the network are reported in blockedAspects instead of rejecting the operation, so an offline "Repair" still fixes everything that is locally fixable.
resolveLaunchVersion	Read the installed version JSON appropriate for a target's loader and merge inheritsFrom.
runRepair	Execute any repair plan. Reuses the install runner.
runVerifyAndRepair	Verify a single aspect and, in 'fix' mode (default), repair every broken file before returning. In 'report' mode the function never touches disk — it returns the verification only and leaves repair as null.
scopedLogger	Wrap a Logger so every message is prefixed with [scope]. Mirrors the scopedLogger(scope) convention used by the launcher: each module reaches for one named logger at the top of the file (e.g. const log = scopedLogger(input.logger, "http")) instead of threading the scope through every callsite.
stripUuidDashes	Strip the dashes from a UUID. Used by ${auth_uuid}.
toOnlineAuth	Project a MojangSession into the OnlineAuth shape that kit.launch.compose accepts.
verifyFabric	Verify the Fabric loader slice: profile JSON + every library it pulls in.
verifyForge	Verify the Forge loader slice: the on-disk Forge version JSON and every library it declares. Libraries can only be enumerated once the JSON is present and parsable; a malformed JSON is surfaced as a CORRUPT issue so repair rewrites it before re-running.
verifyMinecraft	Verify the vanilla Minecraft slice of an installation: the client jar, version JSON, libraries (incl. native jars), assets (index + objects), logging config, and the extracted natives directory.
verifyRuntime	Verify the Java runtime files. Honours target.runtime.installRoot when set so a shared/global runtime install is checked at its real location instead of the per-target runtime/ subfolder.
verifyTargetReadiness	Verify every launch-critical aspect that applies to the target.