stovesdk.js 0.0.0-stage → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 firejune
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,206 @@
-# Temporary Holding Version
+# stovesdk.js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Unofficial Node.js / Electron bindings for the **STOVE PC SDK** (N-API).
+
+The STOVE PC SDK ships official bindings for C, C#, and C++ only. This project wraps the native SDK so Electron and Node.js games can use it the way `steamworks.js` wraps Steamworks.
+
+> **Status: alpha.** Install from npm as `stovesdk.js`; the Windows x64 prebuild ships inside the package and is also attached to each [GitHub release](https://github.com/firejune/stovesdk.js/releases). See *Install* and *Build* below.
+
+## Scope
+
+A thin wrapper around the SDK. No game policy.
+
+- SDK initialize / uninitialize
+- Callback pump (`RunCallback`) for the host event loop
+- Ownership query
+- Achievements and stats
+- Login identity reads (user, country/language)
+
+What a game does when a check fails (blocking, demo modes, messaging, quitting) belongs in the game, not in this module.
+
+## Platform
+
+Windows x64 only, which matches the STOVE PC SDK itself. The addon targets N-API (version 8), so one build works across Node.js and Electron versions without a rebuild for every Electron ABI.
+
+## Bring your own SDK
+
+The STOVE PC SDK is **not** included in this repository and is not redistributed by this package.
+
+1. Download the STOVE PC SDK from the STOVE developer portal under your own developer account.
+2. Place it under [`sdk/`](sdk/README.md), or point `STOVE_PCSDK_DIR` at your copy. The expected layout is documented in `sdk/README.md`; `npm run check-sdk` tells you what is missing.
+
+Your use of the SDK is governed by STOVE's own terms.
+
+## Install
+
+```sh
+npm install stovesdk.js
+```
+
+The package carries the Windows x64 prebuild at `prebuilds/win32-x64/stovesdk.node` (with its `SHA256SUMS`), which is the last place `load()` looks, so the binary needs no further step. Installing compiles nothing: `package.json` sets `"gypfile": false`, so npm does not run the implicit `node-gyp rebuild` that a root `binding.gyp` would otherwise trigger, and the install succeeds on any platform — the JS entry works everywhere, and off Windows `load()` refuses at runtime with code `STOVE_PCSDK_UNSUPPORTED_PLATFORM`.
+
+What you still provide is the SDK: `BaseSDK.dll`, `OwnershipSDK.dll` and `GameSupportSDK.dll` next to the `.node` or next to your executable (see *Build*). They are part of the SDK, not of this package.
+
+### Where `load()` looks
+
+In order; the first file that exists wins:
+
+| Location | How |
+| --- | --- |
+| Any path | `load('C:/path/to/stovesdk.node')` |
+| Any path | `STOVE_PCSDK_ADDON=C:/path/to/stovesdk.node` in the environment |
+| `node_modules/stovesdk.js/build/Release/` | where `npm run build` puts its output |
+| `node_modules/stovesdk.js/prebuilds/win32-x64/` | where the npm package ships the prebuild |
+
+An Electron app usually ships the `.node` in its own resources, next to the three SDK DLLs it has to ship anyway, and calls `load(path)` with that location. When none of the four places has a file, `load()` throws with code `STOVE_PCSDK_ADDON_NOT_FOUND` and lists the paths it tried.
+
+### Installing from a git tag instead
+
+```sh
+npm install github:firejune/stovesdk.js#vX.Y.Z
+```
+
+installs the same package without the prebuild (binaries are not tracked in git). Download `stovesdk.node` and `SHA256SUMS` from the [GitHub release](https://github.com/firejune/stovesdk.js/releases) of the same version, check the sum (`sha256sum -c SHA256SUMS`, or `CertUtil -hashfile stovesdk.node SHA256`), and put the binary in one of the places above. (v0.1.0 still runs `node-gyp rebuild` on install; add `--ignore-scripts` for that one.)
+
+Or build the binary yourself, below.
+
+## Build
+
+On Windows x64 with Visual Studio Build Tools (C++ workload) and Python installed. The pinned build tool (node-gyp 13) declares Node `^22.22.2 || ^24.15.0 || >=26` — that is a requirement of the build, not of the addon, whose runtime floor stays Node 18:
+
+```sh
+npm ci                    # dev dependencies; nothing is compiled on install
+npm run check-sdk         # verifies sdk/ or STOVE_PCSDK_DIR
+npm run build             # node-gyp rebuild → build/Release/stovesdk.node
+for m in BaseSDK OwnershipSDK GameSupportSDK; do
+  cp "$(node tools/sdk-dir.js)/$m/Deploy/Bin/x64/Release/$m.dll" build/Release/
+done                      # the smoke loads the .node, which needs the three SDK DLLs beside it
+npm run smoke             # loads the addon and exercises the paths that need no STOVE client
+```
+
+The `.node` hard-imports `BaseSDK.dll`, `OwnershipSDK.dll` and `GameSupportSDK.dll`. Ship those three DLLs next to the `.node` (or next to your executable) — they are part of the SDK, not of this package. When one is in neither place, `load()` throws with code `STOVE_PCSDK_DLL_NOT_FOUND` naming the missing files and the two directories it checked (see *`load()` errors*).
+
+On other platforms the JS side still works for development, but there is nothing to compile: `npm ci`, then `npm test` and `npm run typecheck` run as they do in CI; `tools/syntax-check.sh` can parse the C++ against your SDK headers with clang as a pre-flight.
+
+## Usage
+
+```js
+const { load, ErrorCode } = require('stovesdk.js')
+
+const stove = load() // throws off Windows, when no build/prebuild exists, or when an SDK DLL is missing (see `load()` errors)
+
+// The SDK delivers every asynchronous result through its callback pump.
+// Run it on the thread that initializes the SDK (the Electron main process), ~16 ms.
+const pump = setInterval(() => stove.runCallbacks(), stove.getAddonInfo().pumpIntervalMs)
+
+async function main() {
+  const init = await stove.initialize({
+    environment: 'LIVE',          // as configured for your title in STOVE Studio
+    gameId: 'YOUR_GAME_ID',
+    applicationKey: 'YOUR_APPLICATION_KEY', // never the Application Secret
+  })
+  if (init.status === 'restart') {
+    // The SDK asked the STOVE client to relaunch the app through the launcher.
+    // The vendor guide expects the app to exit here — that decision is yours.
+    return
+  }
+
+  const { OwnershipCode, OwnershipGameCode } = stove.constants
+  const ownerships = await stove.getOwnershipList()
+  const ownsGame = ownerships.some(
+    o => o.ownershipCode === OwnershipCode.ACQUIRE && o.gameCode === OwnershipGameCode.BASIC
+  )
+
+  // Achievements on STOVE are driven by stats: an achievement is a stat plus a goal,
+  // so "unlocking" one means modifying its stat.
+  await stove.setStat('STAT_ID', 1)
+  const achievement = await stove.getAchievement('ACHIEVEMENT_ID')
+  console.log(ownsGame, achievement.status)
+}
+
+main()
+  .catch(err => {
+    // Every rejection is an Error with { step, sdk, method, code, externalError }.
+    if (err.code === ErrorCode.NOT_INITIALIZED) console.error('call initialize() first')
+    else console.error(err.step, err.code, err.message)
+  })
+  .finally(() => {
+    clearInterval(pump)
+    stove.uninitialize()
+  })
+```
+
+## API
+
+All functions live on the object returned by `load()`. Full types: [`index.d.ts`](index.d.ts).
+
+| Function | SDK call | Returns |
+| --- | --- | --- |
+| `initialize({ environment, gameId, applicationKey, restartWaitMs? })` | `Base_RestartAppIfNecessaryAsync` → `Base_Initialize` | `Promise<{ status: 'ok', result } \| { status: 'restart' }>` |
+| `runCallbacks()` | `Base_RunCallback` | `void` — call periodically; Promises settle from here |
+| `isInitialized()` | — | `boolean` |
+| `uninitialize()` | `GameSupport_UnInitialize`, `Ownership_UnInitialize`, `Base_UnInitialize` (those that were initialized) | `{ gameSupport, ownership, base }` — pending Promises reject with `ErrorCode.ABORTED` |
+| `getOwnershipList()` | `Ownership_OwnershipList` (`Ownership_Initialize` lazily) | `Promise<Ownership[]>` — raw list; interpret with `constants` |
+| `getUser()` | `Base_GetUser` | `{ ok, memberNumber, gameUserId, nickname }` (sync) |
+| `getGds()` | `Base_GetGds` | `{ ok, nation, isDefault, language }` (sync) |
+| `getAchievement(id)` | `GameSupport_Achievement` | `Promise<Achievement>` (a query — completes nothing) |
+| `getAllAchievements()` | `GameSupport_AllAchievement` | `Promise<Achievement[]>` |
+| `getStat(statId)` | `GameSupport_Stat` | `Promise<Stat>` |
+| `setStat(statId, int32)` | `GameSupport_ModifyStat` | `Promise<ModifyStatResult>` |
+| `getVersion()` | `Base_GetVersion` | `{ ok, version }` (sync, informational) |
+| `getAddonInfo()` | — | `{ sdkVersion, napiVersion, arch, platform, pumpIntervalMs }` |
+| `constants` | SDK enums | `OwnershipCode`, `OwnershipGameCode`, `ErrorCode` |
+
+Notes:
+
+- `GameSupport_Initialize` runs lazily on the first achievement/stat call; `Ownership_Initialize` on the first `getOwnershipList()`. Both are torn down by `uninitialize()`, Base last.
+- 64-bit values (`memberNumber`, `purchaseDate`, `updatedAt`) cross as decimal strings so no precision is lost.
+- Synchronous reads (`getUser`, `getGds`) never throw: before `initialize()` they answer `{ ok: false, code: ErrorCode.NOT_INITIALIZED, reason }`.
+- Argument errors throw synchronously (`TypeError` / `RangeError`) before anything reaches the SDK.
+- A stat that has never been written reports `currentValue` as `-2147483648`. That is the SDK's own `int32` value, passed through unchanged.
+- Leave a moment between `uninitialize()` and the next `initialize()`. The STOVE client re-creates its side of the connection after a disconnect, and an immediate re-initialize can answer `{ status: 'restart' }`.
+
+### Error codes
+
+Rejected Promises carry `step`, `sdk`, `method`, `code` and `externalError`. `code` is the SDK's own result code (unsigned) when the SDK answered, or one of these negative addon codes when the addon refused the call:
+
+| `ErrorCode` | Value | Meaning |
+| --- | --- | --- |
+| `NOT_INITIALIZED` | `-1` | `initialize()` has not succeeded, or `uninitialize()` has run |
+| `ALREADY_INITIALIZED` | `-2` | `initialize()` called while the SDK is up |
+| `IN_PROGRESS` | `-3` | the same kind of call is already in flight |
+| `ABORTED` | `-4` | a pending Promise was discarded by `uninitialize()` |
+
+### `load()` errors
+
+`load()` throws synchronously; each error carries a string `code`:
+
+| `code` | When |
+| --- | --- |
+| `STOVE_PCSDK_UNSUPPORTED_PLATFORM` | not Windows |
+| `STOVE_PCSDK_ADDON_NOT_FOUND` | no `stovesdk.node` at the path given, in `STOVE_PCSDK_ADDON`, or in `build/Release/` / `prebuilds/win32-x64/`; the message lists the paths tried |
+| `STOVE_PCSDK_DLL_NOT_FOUND` | the addon exists but one of `BaseSDK.dll`, `OwnershipSDK.dll`, `GameSupportSDK.dll` is next to neither the addon nor the host executable; `missing` and `searched` list the files and directories, `cause` is Node's `ERR_DLOPEN_FAILED` |
+
+When all three DLLs are present and the load still fails, the original error is thrown unchanged — the cause is then outside what this module can see, such as the DLLs' own imports (the SDK requires the VC++ redistributable) or a binary built for another architecture.
+
+## Threading model
+
+SDK callbacks are plain C function pointers with no user-data slot, and the vendor docs do not state which thread they fire on. The addon therefore never touches N-API inside a callback: callbacks copy their result into a mutex-guarded queue, and `runCallbacks()` drains that queue on the JS thread, where it advances the init chain, issues follow-up SDK calls and settles Promises.
+
+## Prebuilds, publishing and CI
+
+[`.github/workflows/prebuild.yml`](.github/workflows/prebuild.yml) is a manually triggered Windows x64 build that expects the SDK to be present on the runner at `STOVE_PCSDK_DIR`. Because the SDK is not public, the workflow does not download it; how CI gets the SDK is an open design question — see the workflow header for the options under consideration. Until it is settled, the prebuild is built by the maintainer and attached to the GitHub release.
+
+[`.github/workflows/publish.yml`](.github/workflows/publish.yml) publishes a tagged release to npm, by manual dispatch once its prebuild is attached: it takes `stovesdk.node` from the GitHub release, checks it against `SHA256SUMS`, checks that the tarball carries that one binary and nothing from the SDK, and publishes over OIDC trusted publishing with provenance. [RELEASING.md](RELEASING.md) has the sequence.
+
+## Contributing and releases
+
+[CONTRIBUTING.md](CONTRIBUTING.md) covers issues, the checks a pull request has to clear and the commit conventions; [RELEASING.md](RELEASING.md) covers how a version is cut and how prebuilds reach a release; [ROADMAP.md](ROADMAP.md) says what comes next.
+
+## Disclaimer
+
+This is an independent project. It is not affiliated with, endorsed by, or supported by Smilegate or STOVE. "STOVE" is a trademark of its respective owner.
+
+## License
+
+[MIT](LICENSE)

package/binding.gyp

@@ -0,0 +1,73 @@
+{
+  # stovesdk.js — N-API addon build (Windows x64 only).
+  #
+  # Why node-gyp (and not cmake-js / napi-rs):
+  #   - The SDK ships as MSVC C++ headers + import libs + DLLs, and its structs have their
+  #     ctors/dtors inside the DLLs. Wrapping that from C++ with node-addon-api is a direct call.
+  #   - node-gyp finds MSVC via vswhere on its own, needs no CMake, and injects the
+  #     win_delay_load_hook that lets a module built against Node headers load inside electron.exe.
+  #     N-API (NAPI_VERSION=8) is the ABI-stable surface, so one .node loads in Node and Electron.
+  #
+  # The SDK is never part of this repository: tools/sdk-dir.js resolves it from STOVE_PCSDK_DIR
+  # or ./sdk and fails with a readable message when the layout is incomplete.
+  'variables': {
+    'stove_pcsdk_dir%': '<!(node tools/sdk-dir.js)',
+    'stove_pcsdk_sdk_version%': '<!(node tools/sdk-dir.js version)',
+  },
+  'targets': [
+    {
+      'target_name': 'stovesdk',
+      'conditions': [
+        ['OS=="win"', {
+          'sources': ['src/stovesdk.cc'],
+          'include_dirs': [
+            "<!@(node -p \"require('node-addon-api').include\")",
+            # Root first: OwnershipSDK/GameSupportSDK headers include
+            # "BaseSDK/Deploy/Include/Misc/Structures.h" relative to this root.
+            '<(stove_pcsdk_dir)',
+            '<(stove_pcsdk_dir)/BaseSDK/Deploy/Include',
+            '<(stove_pcsdk_dir)/OwnershipSDK/Deploy/Include',
+            '<(stove_pcsdk_dir)/GameSupportSDK/Deploy/Include',
+          ],
+          'libraries': [
+            # Import libraries: the .node then hard-imports BaseSDK.dll / OwnershipSDK.dll /
+            # GameSupportSDK.dll. Intentional — a missing DLL fails at require() time as a
+            # catchable JS error instead of an SEH crash on first call that /DELAYLOAD would give.
+            '<(stove_pcsdk_dir)/BaseSDK/Deploy/Lib/x64/Release/BaseSDK.lib',
+            '<(stove_pcsdk_dir)/OwnershipSDK/Deploy/Lib/x64/Release/OwnershipSDK.lib',
+            '<(stove_pcsdk_dir)/GameSupportSDK/Deploy/Lib/x64/Release/GameSupportSDK.lib',
+          ],
+          'defines': [
+            'NAPI_VERSION=8',
+            'NAPI_DISABLE_CPP_EXCEPTIONS',
+            'NOMINMAX',
+            'WIN32_LEAN_AND_MEAN',
+            'UNICODE',
+            '_UNICODE',
+            'STOVE_PCSDK_SDK_VERSION="<(stove_pcsdk_sdk_version)"',
+          ],
+          'msvs_settings': {
+            'VCCLCompilerTool': {
+              'ExceptionHandling': 1,
+              'AdditionalOptions': ['/std:c++17', '/utf-8'],
+            },
+          },
+          'configurations': {
+            'Release': {
+              'msvs_settings': {
+                'VCCLCompilerTool': {
+                  # /MD (dynamic CRT): the SDK DLLs themselves require the VC++ redistributable
+                  # (MSVCP140 / VCRUNTIME140), so matching them adds no new runtime dependency.
+                  'RuntimeLibrary': 2,
+                },
+              },
+            },
+          },
+        }, {
+          # Nothing to build off Windows; keep the target so `node-gyp configure` still succeeds.
+          'type': 'none',
+        }],
+      ],
+    },
+  ],
+}

package/index.d.ts

@@ -0,0 +1,241 @@
+// Type definitions for stovesdk.js — unofficial Node.js / Electron bindings for the STOVE PC SDK.
+
+/** Result of a synchronous SDK call. */
+export interface SdkResult {
+  /** `true` when the SDK reported success. */
+  ok: boolean
+  /** Which SDK module answered (e.g. "BaseSDK"). Empty when the addon refused the call itself. */
+  sdk: string
+  /** SDK method code. */
+  method: number
+  /** SDK result code (unsigned), or a negative {@link ErrorCode} when the addon refused the call. */
+  code: number
+}
+
+/** Result delivered through an SDK callback — carries the SDK's own message as well. */
+export interface SdkCallbackResult extends SdkResult {
+  message: string
+  externalError: number
+}
+
+/** A synchronous read the addon did not forward to the SDK (it is not initialized yet). */
+export interface NotAskedResult extends SdkResult {
+  ok: false
+  reason: string
+}
+
+/**
+ * Error shape for every rejected Promise. `code` is the SDK result code, or one of
+ * {@link ErrorCode} (negative) when the addon itself refused the call.
+ */
+export interface SdkError extends Error {
+  /** Which step failed: "restartAppIfNecessary" | "initialize" | "ownershipInitialize" | "ownershipList" | "gameSupportInitialize" | "achievement" | "allAchievements" | "stat" | "modifyStat" | "uninitialize". */
+  step: string
+  sdk: string
+  method: number
+  code: number
+  externalError: number
+}
+
+/** Addon-level error codes (negative so they never collide with SDK result codes). */
+export declare const ErrorCode: Readonly<{
+  /** `initialize()` has not succeeded (or `uninitialize()` has run). */
+  NOT_INITIALIZED: -1
+  /** `initialize()` was called while the SDK is already initialized. */
+  ALREADY_INITIALIZED: -2
+  /** The same kind of call is already in flight. */
+  IN_PROGRESS: -3
+  /** A pending Promise was discarded by `uninitialize()`. */
+  ABORTED: -4
+}>
+
+export interface InitializeOptions {
+  /** STOVE environment string as given by STOVE Studio for your title (e.g. "LIVE"). */
+  environment: string
+  /** Game ID issued by STOVE Studio. */
+  gameId: string
+  /** Application Key issued by STOVE Studio. Never the Application Secret. */
+  applicationKey: string
+  /** How long the SDK may wait for the STOVE client when checking whether a relaunch is needed. Default 60000. */
+  restartWaitMs?: number
+}
+
+export type InitializeResult =
+  /** The SDK is initialized; start pumping `runCallbacks()` for as long as it stays up. */
+  | { status: 'ok'; result: SdkCallbackResult }
+  /**
+   * The SDK could not attach to a running STOVE client and has asked the client to relaunch the
+   * application. The SDK is NOT initialized. The vendor guide expects the application to exit now.
+   */
+  | { status: 'restart' }
+
+export interface Ownership {
+  gameId: string
+  /** One of {@link constants.OwnershipGameCode}. */
+  gameCode: number
+  /** One of {@link constants.OwnershipCode}. */
+  ownershipCode: number
+  /** 64-bit timestamp as a decimal string. */
+  purchaseDate: string
+  /** 64-bit member number as a decimal string. */
+  memberNumber: string
+}
+
+export interface UserInfo extends SdkResult {
+  memberNumber: string
+  gameUserId: string
+  nickname: string
+}
+
+export interface GdsInfo extends SdkResult {
+  /** Country code of the login. */
+  nation: string
+  /** `true` when the country could not be determined and `nation` is STOVE's default instead. */
+  isDefault: boolean
+  language: string
+}
+
+export interface AchievementCondition {
+  valueOperation: string
+  type: string
+  goalValue: number
+}
+
+export interface Achievement {
+  achievementId: string
+  name: string
+  description: string
+  /** Status string as reported by the SDK (e.g. "ONGOING", "ACHIEVED"). */
+  status: string
+  value: number
+  defaultImageUrl: string
+  achievedImageUrl: string
+  condition: AchievementCondition | null
+  result: SdkCallbackResult
+}
+
+export interface Stat {
+  statId: string
+  gameId: string
+  memberNumber: string
+  /** 64-bit timestamp as a decimal string. */
+  updatedAt: string
+  currentValue: number
+  result: SdkCallbackResult
+}
+
+export interface ModifyStatResult {
+  statId: string
+  /** The value that was sent. */
+  value: number
+  /** The stat's value after the SDK applied the change. */
+  currentValue: number
+  updated: boolean
+  errorMessage: string
+  result: SdkCallbackResult
+}
+
+export interface UninitializeResult {
+  gameSupport: SdkResult | null
+  ownership: SdkResult | null
+  base: SdkResult | null
+}
+
+export interface AddonInfo {
+  /** Contents of `<sdk>/VERSION` at build time, or "unknown". */
+  sdkVersion: string
+  napiVersion: number
+  arch: 'x64'
+  platform: 'win32'
+  /** Suggested `runCallbacks()` interval (vendor guide). */
+  pumpIntervalMs: number
+}
+
+export interface Constants {
+  OwnershipCode: Readonly<{ NONE: number; ACQUIRE: number; LOSE: number }>
+  OwnershipGameCode: Readonly<{ NONE: number; BASIC: number; DEMO: number; DLC: number }>
+  ErrorCode: typeof ErrorCode
+}
+
+/** The native addon surface. */
+export interface StovePcSdk {
+  getAddonInfo(): AddonInfo
+  /** Base_GetVersion. Synchronous, informational; may report `ok: false` before initialization. */
+  getVersion(): SdkResult & { version: string }
+
+  /**
+   * Base_RestartAppIfNecessaryAsync followed by Base_Initialize. Settles from a later
+   * `runCallbacks()` call, so start the pump before awaiting this.
+   */
+  initialize(options: InitializeOptions): Promise<InitializeResult>
+  /** Base_RunCallback plus Promise settlement. Call periodically (see `getAddonInfo().pumpIntervalMs`) on the thread that called `initialize()`. */
+  runCallbacks(): void
+  isInitialized(): boolean
+  /** Uninitializes every module that was initialized (GameSupport, Ownership, then Base). Rejects pending Promises with `ErrorCode.ABORTED`. Safe to call twice. */
+  uninitialize(): UninitializeResult
+
+  /** Ownership_OwnershipList (Ownership_Initialize is called lazily). Returns the raw list; interpret it with `constants`. */
+  getOwnershipList(): Promise<Ownership[]>
+
+  /** Base_GetUser. Synchronous; answers `{ ok: false, code: ErrorCode.NOT_INITIALIZED }` before initialization instead of throwing. */
+  getUser(): UserInfo | NotAskedResult
+  /** Base_GetGds. Synchronous; same refusal shape as `getUser()`. */
+  getGds(): GdsInfo | NotAskedResult
+
+  /** GameSupport_Achievement — a query. Achievements are completed by modifying their stat (`setStat`). */
+  getAchievement(achievementId: string): Promise<Achievement>
+  /** GameSupport_AllAchievement. */
+  getAllAchievements(): Promise<Achievement[]>
+  /** GameSupport_Stat. */
+  getStat(statId: string): Promise<Stat>
+  /** GameSupport_ModifyStat. `value` must be an int32 (throws RangeError otherwise). */
+  setStat(statId: string, value: number): Promise<ModifyStatResult>
+
+  readonly constants: Constants
+}
+
+/** File name of the compiled addon. */
+export declare const ADDON_FILE: 'stovesdk.node'
+
+/** The SDK DLLs the addon imports: `BaseSDK.dll`, `OwnershipSDK.dll`, `GameSupportSDK.dll`. They ship with the SDK, not with this package. */
+export declare const SDK_DLLS: readonly string[]
+
+/** Paths `load()` tries, in order. */
+export declare function candidateAddonPaths(env?: NodeJS.ProcessEnv, baseDir?: string): string[]
+
+/** First existing candidate path; throws (code `STOVE_PCSDK_ADDON_NOT_FOUND`) when none exists. */
+export declare function resolveAddonPath(env?: NodeJS.ProcessEnv, baseDir?: string, exists?: (p: string) => boolean): string
+
+/**
+ * Error `load()` throws when the addon file exists but cannot be loaded because one or more of
+ * {@link SDK_DLLS} is next to neither the addon nor the host executable.
+ */
+export interface DllNotFoundError extends Error {
+  code: 'STOVE_PCSDK_DLL_NOT_FOUND'
+  /** The DLL file names that were not found. */
+  missing: string[]
+  /** The directories that were checked: the addon's and the host executable's. */
+  searched: string[]
+  /** Node's own `ERR_DLOPEN_FAILED` error. */
+  cause: Error
+}
+
+/**
+ * Which of {@link SDK_DLLS} are found neither in the directory of `addonPath` nor in that of
+ * `execPath` (default `process.execPath`). Empty when all three are present.
+ */
+export declare function missingSdkDlls(addonPath: string, execPath?: string, exists?: (p: string) => boolean): string[]
+
+/**
+ * The error `load()` throws when `require(addonPath)` threw `err`: a {@link DllNotFoundError}
+ * when `err` is `ERR_DLOPEN_FAILED` and an SDK DLL is missing, otherwise `err` itself.
+ */
+export declare function explainLoadError(err: unknown, addonPath: string, execPath?: string, exists?: (p: string) => boolean): unknown
+
+/**
+ * Loads the native addon (cached after the first call). Throws with code
+ * `STOVE_PCSDK_UNSUPPORTED_PLATFORM` off Windows, `STOVE_PCSDK_ADDON_NOT_FOUND` when no build
+ * exists, and `STOVE_PCSDK_DLL_NOT_FOUND` ({@link DllNotFoundError}) when the addon is there but
+ * an SDK DLL is not. Any other load failure is rethrown as Node reported it.
+ */
+export declare function load(addonPath?: string): StovePcSdk

package/index.js

@@ -0,0 +1,117 @@
+'use strict'
+
+// Entry point: locates the compiled addon and loads it.
+//
+// Search order (first hit wins):
+//   1. STOVE_PCSDK_ADDON        — explicit path to a .node file
+//   2. ./build/Release/stovesdk.node   — local `npm run build`
+//   3. ./prebuilds/win32-x64/stovesdk.node — CI prebuild dropped into the package
+//
+// DLL lookup: the .node hard-imports BaseSDK.dll / OwnershipSDK.dll / GameSupportSDK.dll. Node
+// loads addons with LOAD_WITH_ALTERED_SEARCH_PATH, so DLLs placed next to the .node are found
+// first; the directory of the host executable is the other place the Windows loader always looks.
+// When the require() fails with ERR_DLOPEN_FAILED, `load()` checks those two directories for the
+// three DLLs and, if any is absent from both, rethrows with code STOVE_PCSDK_DLL_NOT_FOUND naming
+// the files — Node's own message names neither the DLL nor the directory, and reads as if the
+// .node itself were missing.
+//
+// Nothing here imports Electron, so the same file works from plain Node and the Electron main
+// process. The load is lazy and explicit (`load()`) so merely requiring this module on a
+// non-Windows machine (tests, tooling) does not throw.
+
+const fs = require('fs')
+const path = require('path')
+const { SDK_MODULES } = require('./lib/sdk-dir')
+
+const ADDON_FILE = 'stovesdk.node'
+const SDK_DLLS = Object.freeze(SDK_MODULES.map(mod => `${mod}.dll`))
+
+const ErrorCode = Object.freeze({
+  NOT_INITIALIZED: -1,
+  ALREADY_INITIALIZED: -2,
+  IN_PROGRESS: -3,
+  ABORTED: -4,
+})
+
+function candidateAddonPaths(env = process.env, baseDir = __dirname) {
+  const list = []
+  if (env.STOVE_PCSDK_ADDON && env.STOVE_PCSDK_ADDON.trim()) list.push(path.resolve(env.STOVE_PCSDK_ADDON.trim()))
+  list.push(path.join(baseDir, 'build', 'Release', ADDON_FILE))
+  list.push(path.join(baseDir, 'prebuilds', 'win32-x64', ADDON_FILE))
+  return list
+}
+
+function resolveAddonPath(env = process.env, baseDir = __dirname, exists = fs.existsSync) {
+  const candidates = candidateAddonPaths(env, baseDir)
+  const found = candidates.find(exists)
+  if (found) return found
+  const err = new Error(
+    `[stovesdk] compiled addon not found. Looked in:\n${candidates.map(c => `  - ${c}`).join('\n')}\n` +
+      'Build it with `npm run build` on Windows x64 (with the SDK under sdk/ or STOVE_PCSDK_DIR), ' +
+      'or set STOVE_PCSDK_ADDON to a prebuilt .node file.'
+  )
+  err.code = 'STOVE_PCSDK_ADDON_NOT_FOUND'
+  throw err
+}
+
+// The directories this module can vouch for: the addon's own and the host executable's. The
+// Windows loader also searches the system directories and PATH, but a consumer does not put
+// the SDK there, so a DLL absent from these two is reported as not found.
+function sdkDllSearchDirs(addonPath, execPath = process.execPath) {
+  return [...new Set([path.dirname(path.resolve(addonPath)), path.dirname(path.resolve(execPath))])]
+}
+
+// The SDK DLLs found in none of those directories. Empty when all three are present — then a
+// failed load has another cause (a DLL built for another architecture, its own imports such as
+// the VC++ runtime missing), and the original error says more than this module can.
+function missingSdkDlls(addonPath, execPath = process.execPath, exists = fs.existsSync) {
+  const dirs = sdkDllSearchDirs(addonPath, execPath)
+  return SDK_DLLS.filter(dll => !dirs.some(dir => exists(path.join(dir, dll))))
+}
+
+// The error `load()` throws when `require(addonPath)` threw `err`: a coded error naming the
+// missing SDK DLLs when that is what happened, otherwise `err` itself, untouched.
+function explainLoadError(err, addonPath, execPath = process.execPath, exists = fs.existsSync) {
+  if (!err || err.code !== 'ERR_DLOPEN_FAILED') return err
+  const missing = missingSdkDlls(addonPath, execPath, exists)
+  if (!missing.length) return err
+  const searched = sdkDllSearchDirs(addonPath, execPath)
+  const explained = new Error(
+    `[stovesdk] the addon imports ${SDK_DLLS.join(', ')}; ` +
+      `${missing.join(', ')} ${missing.length === 1 ? 'was' : 'were'} not found next to the addon or next to the host executable. Looked in:\n` +
+      `${searched.map(dir => `  - ${dir}`).join('\n')}\n` +
+      `Copy the SDK's <Module>/Deploy/Bin/x64/Release/<Module>.dll files beside ${path.resolve(addonPath)} ` +
+      'or beside your executable. They are part of the STOVE PC SDK, not of this package.',
+    { cause: err }
+  )
+  explained.code = 'STOVE_PCSDK_DLL_NOT_FOUND'
+  explained.missing = missing
+  explained.searched = searched
+  return explained
+}
+
+let cached = null
+
+function load(addonPath) {
+  if (cached) return cached
+  if (process.platform !== 'win32') {
+    const err = new Error(`[stovesdk] the STOVE PC SDK is Windows-only (platform: ${process.platform})`)
+    err.code = 'STOVE_PCSDK_UNSUPPORTED_PLATFORM'
+    throw err
+  }
+  const file = addonPath ? path.resolve(addonPath) : resolveAddonPath()
+  if (!fs.existsSync(file)) {
+    const err = new Error(`[stovesdk] addon not found: ${file}`)
+    err.code = 'STOVE_PCSDK_ADDON_NOT_FOUND'
+    throw err
+  }
+  try {
+    // eslint-disable-next-line global-require -- native module, resolved at runtime by design
+    cached = require(file)
+  } catch (err) {
+    throw explainLoadError(err, file)
+  }
+  return cached
+}
+
+module.exports = { ADDON_FILE, SDK_DLLS, ErrorCode, candidateAddonPaths, resolveAddonPath, missingSdkDlls, explainLoadError, load }