@shieldbattery/danimoth 0.0.0-stage → 0.1.1

package/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.bat]
+end_of_line = crlf
+
+[*.rs]
+indent_size = 4

package/.gitattributes

@@ -0,0 +1,25 @@
+# Force unix style line endings for everything
+* text eol=lf
+
+*.ico binary
+*.png binary
+*.jpg binary
+*.ai binary
+*.scm binary
+*.scx binary
+*.msi binary
+*.exe binary
+*.diff binary
+*.dll binary
+*.opus binary
+*.mp4 binary
+*.afdesign binary
+
+# Custom for Visual Studio
+*.sln    merge=union
+*.csproj merge=union
+*.vbproj merge=union
+*.fsproj merge=union
+*.dbproj merge=union
+
+*.bat eol=crlf

package/.prettierignore

@@ -0,0 +1 @@
+pnpm-lock.yaml

package/.prettierrc

@@ -0,0 +1,10 @@
+{
+  "arrowParens": "avoid",
+  "bracketSameLine": true,
+  "endOfLine": "lf",
+  "jsxSingleQuote": true,
+  "printWidth": 100,
+  "semi": false,
+  "singleQuote": true,
+  "trailingComma": "all"
+}

package/AGENTS.md

@@ -0,0 +1,25 @@
+# AGENTS.md
+
+Guidance for AI agents working in this repository.
+
+- This is a Neon (Rust) Node.js native module, consumed by the ShieldBattery Electron app's main
+  process. The Rust crate lives in `native/`; `index.js` loads the built `prebuilds/x64.node`.
+- Never commit or publish the Discord Social SDK (`discord_partner_sdk.dll`, `discordpp.h`, or any
+  other file from the SDK download). Keep a local copy under `sdk/`, which is gitignored and
+  excluded from the package.
+- Never commit secrets: OAuth client secrets, access or refresh tokens, `.env` files. The repo is
+  public. Tests never need a token, and tokens for manual testing stay outside the checkout.
+- Keep the module free of any one application's details. Application IDs, launch commands and
+  scheme names are passed in by the app using it, never hardcoded here.
+- The SDK's C API is declared by hand in `native/src/sys.rs` and the DLL is loaded at runtime, so the
+  module builds without the SDK. Every declaration must match `cdiscord.h` from the local SDK copy
+  exactly; when moving to a new SDK version, check each one against the new header.
+- SDK callbacks reach JS through a Neon `Channel`, never by calling JS directly, so it doesn't
+  matter which thread the SDK calls them on. A callback that hands over a `Discord_ClientResult*`
+  or a `Discord_String` gives ownership to the callee: drop the result and `Discord_Free` the
+  string (see `discordpp.h`, which shows the ownership rules for every function).
+- Keep `version` in `native/Cargo.toml` equal to `version` in `package.json`.
+- Run `pnpm test`, `pnpm run format:check`, `cargo fmt --all -- --check` and
+  `cargo clippy --all-targets -- -D warnings` (the last two in `native/`) before committing; CI runs
+  the same checks.
+- Every export needs a matching declaration in `index.d.ts`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShieldBattery
+
+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,103 @@
-# Temporary Holding Version
+# @shieldbattery/danimoth
 
-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.
+Rust-based Node.js native module wrapping the Discord Social SDK.
+
+## The Discord Social SDK is not included
+
+Neither this repo nor the published package contains the Discord Social SDK
+(`discord_partner_sdk.dll`, its headers, or anything else from the download). It comes from the
+Downloads page of the Discord Developer Portal once the Social SDK is enabled for the application.
+Keep a local copy under `sdk/`, which is gitignored and excluded from the package, by extracting
+the download's `discord_social_sdk` folder there (so the DLL ends up at
+`sdk/discord_social_sdk/bin/release/discord_partner_sdk.dll`).
+
+The module builds without the SDK: it loads the DLL at runtime from a path the app passes to
+`loadSdk`, so the app decides where the DLL lives and how it gets there. The C API declarations in
+`native/src/sys.rs` are written by hand against SDK 1.10.
+
+## Usage
+
+```js
+const discord = require('@shieldbattery/danimoth')
+
+discord.loadSdk('C:\\path\\to\\discord_partner_sdk.dll')
+// Client callbacks and promise completions only happen while runCallbacks runs.
+setInterval(() => discord.runCallbacks(), 100)
+
+const client = discord.createClient({
+  onLog: (message, severity) => console.log(`[discord:${severity}] ${message}`),
+  onStatusChanged: status => {
+    if (status === 'ready') {
+      discord.updateRichPresence(client, {
+        details: 'Ranked 1v1',
+        state: 'Terran vs Zerg',
+        timestamps: { start: Date.now() },
+      })
+    }
+  },
+  onTokenExpiring: () => {
+    // Get a new access token and pass it to updateToken.
+  },
+  onActivityJoin: joinSecret => {
+    // Join whatever the secret identifies.
+  },
+})
+await discord.updateToken(client, accessToken)
+discord.connect(client)
+```
+
+See `index.d.ts` for the whole API.
+
+## OS support
+
+Currently we only build for x64 Windows.
+
+## Local development
+
+Build the module and copy it to where `index.js` loads it from:
+
+```sh
+pnpm install
+pnpm run build-debug
+pnpm run tag-prebuild
+```
+
+To consume your local copy from the ShieldBattery app, point the dependency in
+`ShieldBattery/app/package.json` at this directory with pnpm's `link:` protocol, then install. The
+path is relative to the `app` directory; with the two checkouts side by side it is:
+
+```json
+"@shieldbattery/danimoth": "link:../../danimoth"
+```
+
+```sh
+cd path/to/ShieldBattery/app
+pnpm install
+```
+
+After rebuilding here, run `build-debug` and `tag-prebuild` again, then rebuild the app. It picks up
+the new `prebuilds/x64.node` through the link without reinstalling.
+
+## Tests
+
+```sh
+pnpm test
+```
+
+This runs the Rust tests, builds the module, and runs the Node tests in `test/` against the build.
+The tests in `test/sdk.test.js` load the real SDK from the local copy under `sdk/` (or from the path
+in `DANIMOTH_SDK_DLL`) and are skipped when it isn't there, as in CI. They don't connect to Discord.
+
+## Releasing
+
+Run the "Release package" workflow from the Actions tab with the new version number. It sets the
+version in `package.json` and `native/Cargo.toml` (kept equal; the tests fail if they differ), runs
+the tests, builds the release binary, publishes to npm, and pushes a "Version X" commit and a tag
+with the bare version (`1.0.0`, not `v1.0.0`), matching the other ShieldBattery native modules.
+
+The workflow publishes as an npm trusted publisher through GitHub's OIDC token, so no npm token is
+stored in the repo or its secrets. The binary isn't code signed yet.
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,229 @@
+// This implementation is based on type-fest's Opaque, just want to avoid needing the dep
+declare const tag: unique symbol
+declare type Tagged<Token> = {
+  readonly [tag]: Token
+}
+
+/** A Discord Social SDK client created by `createClient`. */
+export type DiscordClient = Tagged<'DiscordClient'>
+
+/** Returns the version of this module, so a caller can tell which build of it was loaded. */
+export function version(): string
+
+/**
+ * Loads the Discord Social SDK from the `discord_partner_sdk.dll` at `dllPath`. Every other
+ * function except `version` throws until this succeeds. Once the SDK is loaded, later calls do
+ * nothing; it stays loaded until the process exits.
+ *
+ * The module is written against SDK 1.10; check `sdkVersion` before relying on another version.
+ */
+export function loadSdk(dllPath: string): void
+
+/** The version of the loaded SDK. */
+export interface SdkVersion {
+  major: number
+  minor: number
+  patch: number
+  hash: string
+}
+
+/** Returns the version of the loaded SDK. */
+export function sdkVersion(): SdkVersion
+
+/**
+ * Runs the SDK's pending callbacks: client callbacks and the completion of pending calls happen
+ * only while this runs. Call it periodically (e.g. every 100ms) for as long as any client exists.
+ */
+export function runCallbacks(): void
+
+export type ClientStatus =
+  | 'disconnected'
+  | 'connecting'
+  | 'connected'
+  | 'ready'
+  | 'reconnecting'
+  | 'disconnecting'
+  | 'httpWait'
+  /** A status this module doesn't know about, from a newer SDK. */
+  | 'unknown'
+
+export type ClientError =
+  | 'none'
+  | 'connectionFailed'
+  | 'unexpectedClose'
+  | 'connectionCanceled'
+  /** An error this module doesn't know about, from a newer SDK. */
+  | 'unknown'
+
+export type LogSeverity = 'verbose' | 'info' | 'warning' | 'error'
+
+/**
+ * Callbacks for a client's events. They're called asynchronously on the JS thread, after the
+ * `runCallbacks` call that received them.
+ */
+export interface ClientOptions {
+  /** Called with each message the SDK logs at `logSeverity` or above. */
+  onLog?: (message: string, severity: LogSeverity | 'unknown') => void
+  /** The lowest severity passed to `onLog`. Defaults to 'info'. */
+  logSeverity?: LogSeverity
+  /**
+   * Called when the client's connection status changes. `errorDetail` is a code that further
+   * describes `error`. The client is only usable once the status is 'ready'.
+   */
+  onStatusChanged?: (status: ClientStatus, error: ClientError, errorDetail: number) => void
+  /**
+   * Called once when the token last passed to `updateToken` is about to expire or has expired.
+   * Get a new token and pass it to `updateToken`. Not called for a token that was expired or
+   * revoked when connecting; the client disconnects instead.
+   */
+  onTokenExpiring?: () => void
+  /**
+   * Called when the user accepts an invite to, or asks to join, another user's activity in the
+   * Discord client, with the `joinSecret` of that activity. If the Discord client launched the
+   * app for this (see `registerLaunchCommand`), it's called once the app connects.
+   */
+  onActivityJoin?: (joinSecret: string) => void
+}
+
+/**
+ * Creates a client. It does nothing until it's given a token (`updateToken`) and connected
+ * (`connect`), or given an application ID (`setApplicationId`) to set rich presence through the
+ * Discord desktop client without connecting.
+ *
+ * The client keeps its callbacks until it's destroyed, and the callbacks often reference the
+ * client, so it isn't garbage collected on its own: call `destroyClient` when done with it.
+ */
+export function createClient(options: ClientOptions): DiscordClient
+
+/**
+ * Drops the client: it disconnects, stops calling its callbacks, and rejects its pending calls.
+ * Any later call with it throws.
+ */
+export function destroyClient(client: DiscordClient): void
+
+/**
+ * Sets the application to use when not connected, for setting rich presence through the Discord
+ * desktop client. Connecting sets it from the token instead.
+ */
+export function setApplicationId(client: DiscordClient, applicationId: string): void
+
+/**
+ * Sets the OAuth2 access token (a Bearer token) the client connects with. If the client is
+ * connected, it may reconnect with the new token. Resolves once the token is stored; wait for that
+ * before calling `connect`.
+ */
+export function updateToken(client: DiscordClient, token: string): Promise<void>
+
+/**
+ * Connects the client to Discord. Progress is reported to `onStatusChanged`; the client is ready
+ * to use once the status is 'ready'.
+ */
+export function connect(client: DiscordClient): void
+
+/** Disconnects the client. Progress is reported to `onStatusChanged`. */
+export function disconnect(client: DiscordClient): void
+
+/** Returns the client's current connection status. */
+export function getStatus(client: DiscordClient): ClientStatus
+
+export type ActivityType = 'playing' | 'streaming' | 'listening' | 'watching' | 'competing'
+
+export type ActivityGamePlatform =
+  'desktop' | 'xbox' | 'samsung' | 'ios' | 'android' | 'embedded' | 'ps4' | 'ps5'
+
+/**
+ * A rich presence activity. The SDK validates the fields when it's set: strings noted as 2-128
+ * characters must be that long if given. The activity's name and application come from the
+ * Discord application and can't be set.
+ */
+export interface Activity {
+  /** Defaults to 'playing'. */
+  type?: ActivityType
+  /** Which field the user's status line in Discord shows. Defaults to the application's name. */
+  statusDisplayType?: 'name' | 'state' | 'details'
+  /** What the user is doing, e.g. the game mode. 2-128 characters. */
+  details?: string
+  /** The state of the user's party, e.g. "In a lobby". 2-128 characters. */
+  state?: string
+  /**
+   * In milliseconds since the Unix epoch. With `start`, Discord shows how long the activity has
+   * been going; with `end`, how long it has left.
+   */
+  timestamps?: { start?: number; end?: number }
+  /**
+   * Images and their tooltips. An image is the key of an art asset uploaded to the Discord
+   * application, or a URL. Tooltips are 2-128 characters.
+   */
+  assets?: {
+    largeImage?: string
+    largeText?: string
+    smallImage?: string
+    smallText?: string
+  }
+  /**
+   * The group the user is in, shown as "(currentSize of maxSize)" after `state`. Everyone in the
+   * party should use the same `id` (2-128 characters). A `maxSize` of 0 shows no maximum.
+   * `privacy` defaults to 'private'.
+   */
+  party?: {
+    id: string
+    currentSize: number
+    maxSize: number
+    privacy?: 'public' | 'private'
+  }
+  /**
+   * Makes the activity joinable from Discord (with a `party` that has room) and is passed to
+   * `onActivityJoin` of whoever joins. 2-128 characters.
+   */
+  joinSecret?: string
+  /** The platforms the activity can be joined from. */
+  supportedPlatforms?: ActivityGamePlatform[]
+  /** Up to 2 buttons that open a URL. They aren't shown to the user themselves. */
+  buttons?: Array<{ label: string; url: string }>
+}
+
+export type ResultErrorType =
+  | 'none'
+  | 'networkError'
+  | 'httpError'
+  | 'clientNotReady'
+  | 'disabled'
+  | 'clientDestroyed'
+  | 'validationError'
+  | 'aborted'
+  | 'authorizationFailed'
+  | 'rpcError'
+  /** An error type this module doesn't know about, from a newer SDK. */
+  | 'unknown'
+
+/** The error a call's promise rejects with when the SDK reports a failure. */
+export interface DiscordCallError extends Error {
+  errorType: ResultErrorType
+  /** A code that further describes the error, e.g. Discord's error code for an HTTP error. */
+  errorCode: number
+  /** Whether the call may succeed if it's tried again. */
+  retryable: boolean
+  /** How long to wait before trying again, in seconds. */
+  retryAfter: number
+}
+
+/**
+ * Sets the user's rich presence. Resolves once Discord accepted it, or rejects with a
+ * `DiscordCallError`.
+ */
+export function updateRichPresence(client: DiscordClient, activity: Activity): Promise<void>
+
+/** Clears the user's rich presence. */
+export function clearRichPresence(client: DiscordClient): void
+
+/**
+ * Registers the command the Discord client runs to launch the app when the user joins an activity
+ * from Discord while the app isn't running. Registration is per machine; do it on every start.
+ * `command` is an executable path plus any arguments, e.g. `"C:\path\app.exe" app-scheme://`; an
+ * empty string registers the running executable. Returns whether it was registered.
+ */
+export function registerLaunchCommand(
+  client: DiscordClient,
+  applicationId: string,
+  command: string,
+): boolean

package/index.js

@@ -0,0 +1 @@
+module.exports = require('./prebuilds/x64.node')

package/native/Cargo.lock

@@ -0,0 +1,180 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "cfg-if"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
+
+[[package]]
+name = "danimoth"
+version = "0.1.1"
+dependencies = [
+ "libloading",
+ "neon",
+]
+
+[[package]]
+name = "either"
+version = "1.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0e9c71c2167ca323c882b99918929403426e2373ea17242ff5653e0d5e1058be"
+
+[[package]]
+name = "getrandom"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "wasi",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.191"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
+
+[[package]]
+name = "libloading"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
+dependencies = [
+ "cfg-if",
+ "windows-link",
+]
+
+[[package]]
+name = "linkme"
+version = "0.3.37"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3045e122bd98aef8ec3ad58ce84f0791f64e70163d1a02710af4aa11a4d54cc5"
+dependencies = [
+ "linkme-impl",
+]
+
+[[package]]
+name = "linkme-impl"
+version = "0.3.37"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77060ebe535362c3da75682cd17b0431017b6e7c5661e714fc69a7ad017d1301"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "neon"
+version = "1.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "70dbe899caa46aa63af21b88b4d345c7259c75c36d92e7d7531f658fb459becd"
+dependencies = [
+ "either",
+ "getrandom",
+ "libloading",
+ "linkme",
+ "neon-macros",
+ "once_cell",
+ "semver",
+ "send_wrapper",
+ "smallvec",
+]
+
+[[package]]
+name = "neon-macros"
+version = "1.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fdc6c9b9844577c69901eb0b690dc282e31172b934364536bbce1cc47639e1b7"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "semver"
+version = "1.0.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
+
+[[package]]
+name = "send_wrapper"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cd0b0ec5f1c1ca621c432a25813d8d60c88abe6d3e08a3eb9cf37d97a0fe3d73"
+
+[[package]]
+name = "smallvec"
+version = "1.16.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5b3dc8af474f516a851ff4bd12db780f948b9250ad37211e4eec0bccea54e01b"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"

package/native/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "danimoth"
+# Kept equal to the version in package.json: `version()` reports this one, and the tests check
+# that the two match.
+version = "0.1.1"
+description = "Rust-based Node.js native module wrapping the Discord Social SDK"
+license = "MIT"
+edition = "2024"
+exclude = ["index.node"]
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+libloading = "0.8"
+neon = "1.1"