twitchdropsminer-cli 0.1.0

package/dist/ops/systemd.js

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+function getUserSystemdDir() {
+    const home = os.homedir();
+    const dir = path.join(home, ".config", "systemd", "user");
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    return dir;
+}
+export function getUnitPath(opts) {
+    const name = opts.serviceName ?? "tdm.service";
+    if (opts.userUnit) {
+        return path.join(getUserSystemdDir(), name);
+    }
+    return path.join("/etc/systemd/system", name);
+}
+export function generateUnitContents(opts) {
+    const nodePath = process.execPath;
+    const cliEntry = process.argv[1];
+    const isUserUnit = opts.userUnit;
+    const lines = [
+        "[Unit]",
+        "Description=Twitch Drops Miner CLI",
+        "After=network-online.target",
+        "Wants=network-online.target",
+        "",
+        "[Service]",
+        `ExecStart=${nodePath} ${cliEntry} run`,
+        "Restart=on-failure",
+        "RestartSec=5",
+        "Type=simple",
+        "Environment=TDM_LOG_LEVEL=info",
+        "NoNewPrivileges=true",
+        "",
+        "[Install]",
+        "WantedBy=default.target"
+    ];
+    // For user units, systemd already runs as the invoking user; adding User= breaks them.
+    if (!isUserUnit) {
+        const user = os.userInfo().username;
+        const serviceIndex = lines.indexOf("[Service]");
+        if (serviceIndex !== -1) {
+            lines.splice(serviceIndex + 2, 0, `User=${user}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function writeUnitFile(opts) {
+    const unitPath = getUnitPath(opts);
+    const contents = generateUnitContents(opts);
+    fs.writeFileSync(unitPath, contents, { mode: 0o644 });
+    return unitPath;
+}
+export function systemctl(args, user) {
+    return new Promise((resolve) => {
+        const fullArgs = [...(user ? ["--user"] : []), ...args];
+        const child = spawn("systemctl", fullArgs, { stdio: "inherit" });
+        child.on("close", (code) => resolve(code ?? 0));
+    });
+}

package/dist/state/authStore.js

@@ -0,0 +1,38 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+function getConfigDir() {
+    const home = os.homedir();
+    const dir = path.join(home, ".config", "tdm");
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    return dir;
+}
+function getAuthFilePath() {
+    return path.join(getConfigDir(), "auth.json");
+}
+export function loadAuthState() {
+    const file = getAuthFilePath();
+    if (!fs.existsSync(file)) {
+        return null;
+    }
+    try {
+        const raw = fs.readFileSync(file, "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveAuthState(state) {
+    const file = getAuthFilePath();
+    const payload = {
+        accessToken: state.accessToken,
+        cookiesHeader: state.cookiesHeader,
+        updatedAt: new Date().toISOString()
+    };
+    const json = JSON.stringify(payload, null, 2);
+    fs.writeFileSync(file, json, { mode: 0o600 });
+}

package/dist/state/cookieStore.js

@@ -0,0 +1,21 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+function cookieDir() {
+    const dir = path.join(os.homedir(), ".config", "tdm");
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
+function cookiePath() {
+    return path.join(cookieDir(), "cookies.txt");
+}
+export function loadCookieHeader() {
+    const p = cookiePath();
+    if (!fs.existsSync(p)) {
+        return null;
+    }
+    return fs.readFileSync(p, "utf8").trim() || null;
+}
+export function saveCookieHeader(cookieHeader) {
+    fs.writeFileSync(cookiePath(), cookieHeader, { mode: 0o600 });
+}

package/dist/state/sessionState.js

@@ -0,0 +1,26 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+function stateDir() {
+    const dir = path.join(os.homedir(), ".local", "state", "tdm");
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
+function sessionPath() {
+    return path.join(stateDir(), "session.json");
+}
+export function loadSessionState() {
+    const p = sessionPath();
+    if (!fs.existsSync(p)) {
+        return null;
+    }
+    try {
+        return JSON.parse(fs.readFileSync(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveSessionState(next) {
+    fs.writeFileSync(sessionPath(), JSON.stringify(next, null, 2), { mode: 0o600 });
+}

package/dist/tests/index.js

@@ -0,0 +1,7 @@
+import "./unit/tokenImport.test.js";
+import "./unit/channel.test.js";
+import "./unit/channelService.test.js";
+import "./unit/dropsDomain.test.js";
+import "./unit/twitchSpade.test.js";
+import "./integration/configStore.test.js";
+import "./parity/stateMachineFlow.test.js";

package/dist/tests/integration/configStore.test.js

@@ -0,0 +1,8 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { loadConfig } from "../../config/store.js";
+test("loadConfig returns defaults when config missing/invalid", () => {
+    const cfg = loadConfig();
+    assert.ok(cfg);
+    assert.equal(typeof cfg.connectionQuality, "number");
+});

package/dist/tests/parity/stateMachineFlow.test.js

@@ -0,0 +1,14 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { StateMachine } from "../../core/stateMachine.js";
+test("state machine supports expected flow states", () => {
+    const sm = new StateMachine();
+    sm.setState("INVENTORY_FETCH");
+    assert.equal(sm.state, "INVENTORY_FETCH");
+    sm.setState("GAMES_UPDATE");
+    assert.equal(sm.state, "GAMES_UPDATE");
+    sm.setState("CHANNELS_FETCH");
+    assert.equal(sm.state, "CHANNELS_FETCH");
+    sm.setState("CHANNEL_SWITCH");
+    assert.equal(sm.state, "CHANNEL_SWITCH");
+});

package/dist/tests/unit/channel.test.js

@@ -0,0 +1,73 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { canWatchChannel, sortChannelCandidates, getChannelPriority, shouldSwitchChannel } from "../../domain/channel.js";
+test("canWatchChannel requires online, drops enabled, and wanted game", () => {
+    const ok = canWatchChannel({
+        id: "1",
+        login: "alpha",
+        online: true,
+        viewers: 100,
+        gameName: "GameA",
+        dropsEnabled: true
+    }, ["GameA"]);
+    assert.equal(ok, true);
+});
+test("sortChannelCandidates prioritizes wanted game then viewers", () => {
+    const sorted = sortChannelCandidates([
+        { id: "1", login: "a", online: true, viewers: 50, gameName: "GameB", dropsEnabled: true },
+        { id: "2", login: "b", online: true, viewers: 10, gameName: "GameA", dropsEnabled: true }
+    ], ["GameA", "GameB"]);
+    assert.equal(sorted[0]?.id, "2");
+});
+test("getChannelPriority prefers ACL then game order then viewers", () => {
+    const wanted = ["GameA", "GameB"];
+    const acl = {
+        id: "acl",
+        login: "acl_ch",
+        online: true,
+        viewers: 5,
+        gameName: "GameB",
+        dropsEnabled: true,
+        aclBased: true
+    };
+    const nonAcl = {
+        id: "dir",
+        login: "dir_ch",
+        online: true,
+        viewers: 1000,
+        gameName: "GameA",
+        dropsEnabled: true,
+        aclBased: false
+    };
+    assert.ok(getChannelPriority(acl, wanted) < getChannelPriority(nonAcl, wanted));
+    const sorted = sortChannelCandidates([nonAcl, acl], wanted);
+    assert.equal(sorted[0]?.id, "acl");
+});
+test("shouldSwitchChannel returns true when current is null or candidate has higher priority", () => {
+    const wanted = ["GameA", "GameB"];
+    const low = {
+        id: "1",
+        login: "low",
+        online: true,
+        viewers: 10,
+        gameName: "GameB",
+        dropsEnabled: true
+    };
+    const high = {
+        id: "2",
+        login: "high",
+        online: true,
+        viewers: 100,
+        gameName: "GameA",
+        dropsEnabled: true
+    };
+    assert.equal(shouldSwitchChannel(null, high, wanted), true);
+    assert.equal(shouldSwitchChannel(low, high, wanted), true);
+    assert.equal(shouldSwitchChannel(high, low, wanted), false);
+});
+test("channels without wanted game or dropsEnabled are filtered by canWatchChannel", () => {
+    const wanted = ["GameA"];
+    assert.equal(canWatchChannel({ id: "1", login: "x", online: true, viewers: 1, gameName: "Other", dropsEnabled: true }, wanted), false);
+    assert.equal(canWatchChannel({ id: "2", login: "y", online: true, viewers: 1, gameName: "GameA", dropsEnabled: false }, wanted), false);
+    assert.equal(canWatchChannel({ id: "3", login: "z", online: true, viewers: 1, gameName: "GameA", dropsEnabled: true }, wanted), true);
+});

package/dist/tests/unit/channelService.test.js

@@ -0,0 +1,41 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { parseGameDirectoryResponse } from "../../core/channelService.js";
+test("parseGameDirectoryResponse extracts channels from directory payload", () => {
+    const response = {
+        data: {
+            game: {
+                streams: {
+                    edges: [
+                        {
+                            node: {
+                                broadcasters: [{ id: "123", login: "streamer1" }],
+                                viewersCount: 500,
+                                game: { displayName: "Just Chatting" }
+                            }
+                        },
+                        {
+                            node: {
+                                broadcaster: { id: "456", login: "streamer2" },
+                                viewerCount: 100,
+                                game: { name: "Fallout" }
+                            }
+                        }
+                    ]
+                }
+            }
+        }
+    };
+    const channels = parseGameDirectoryResponse(response, "Just Chatting", false);
+    assert.equal(channels.length, 2);
+    assert.equal(channels[0]?.id, "123");
+    assert.equal(channels[0]?.login, "streamer1");
+    assert.equal(channels[0]?.viewers, 500);
+    assert.equal(channels[0]?.gameName, "Just Chatting");
+    assert.equal(channels[0]?.online, true);
+    assert.equal(channels[0]?.dropsEnabled, true);
+    assert.equal(channels[1]?.id, "456");
+    assert.equal(channels[1]?.login, "streamer2");
+    assert.equal(channels[1]?.viewers, 100);
+    assert.equal(channels[1]?.aclBased, false);
+});

package/dist/tests/unit/dropsDomain.test.js

@@ -0,0 +1,57 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { DropsCampaign } from "../../domain/inventory.js";
+test("TimedDrop canClaim respects 24h post-campaign window", () => {
+    const now = new Date();
+    const campaignRaw = {
+        id: "c1",
+        name: "Test Campaign",
+        game: { name: "GameA", slug: "gamea" },
+        self: { isAccountConnected: true },
+        startAt: new Date(now.getTime() - 60 * 60 * 1000).toISOString(),
+        endAt: new Date(now.getTime() - 30 * 60 * 1000).toISOString(),
+        status: "ACTIVE",
+        timeBasedDrops: [
+            {
+                id: "d1",
+                name: "Drop1",
+                startAt: new Date(now.getTime() - 60 * 60 * 1000).toISOString(),
+                endAt: new Date(now.getTime() - 30 * 60 * 1000).toISOString(),
+                requiredMinutesWatched: 30,
+                benefitEdges: [{ benefit: { id: "b1", name: "Reward", distributionType: "DIRECT_ENTITLEMENT", imageAssetURL: "" } }],
+                self: { dropInstanceID: "inst1", isClaimed: false, currentMinutesWatched: 30 },
+                preconditionDrops: []
+            }
+        ]
+    };
+    const campaign = new DropsCampaign(campaignRaw, {}, true);
+    const drop = Array.from(campaign.timedDrops.values())[0];
+    assert.equal(drop.canClaim, true);
+});
+test("DropsCampaign canEarnWithin filters by timeframe and eligibility", () => {
+    const now = new Date();
+    const campaignRaw = {
+        id: "c2",
+        name: "Test Campaign 2",
+        game: { name: "GameB", slug: "gameb" },
+        self: { isAccountConnected: true },
+        startAt: new Date(now.getTime() - 10 * 60 * 1000).toISOString(),
+        endAt: new Date(now.getTime() + 50 * 60 * 1000).toISOString(),
+        status: "ACTIVE",
+        timeBasedDrops: [
+            {
+                id: "d2",
+                name: "Drop2",
+                startAt: new Date(now.getTime() - 10 * 60 * 1000).toISOString(),
+                endAt: new Date(now.getTime() + 50 * 60 * 1000).toISOString(),
+                requiredMinutesWatched: 30,
+                benefitEdges: [{ benefit: { id: "b2", name: "Reward", distributionType: "DIRECT_ENTITLEMENT", imageAssetURL: "" } }],
+                self: { dropInstanceID: null, isClaimed: false, currentMinutesWatched: 0 },
+                preconditionDrops: []
+            }
+        ]
+    };
+    const campaign = new DropsCampaign(campaignRaw, {}, true);
+    const stamp = new Date(now.getTime() + 30 * 60 * 1000);
+    assert.equal(campaign.canEarnWithin(stamp), true);
+});

package/dist/tests/unit/tokenImport.test.js

@@ -0,0 +1,13 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { parseTokenInput } from "../../auth/tokenImport.js";
+test("parseTokenInput supports raw token", () => {
+    const parsed = parseTokenInput("abc123");
+    assert.equal(parsed.accessToken, "abc123");
+    assert.equal(parsed.source, "raw");
+});
+test("parseTokenInput supports auth-token pair", () => {
+    const parsed = parseTokenInput("auth-token=abc123");
+    assert.equal(parsed.accessToken, "abc123");
+    assert.equal(parsed.source, "auth-token");
+});

package/dist/tests/unit/twitchSpade.test.js

@@ -0,0 +1,24 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildSpadePayload } from "../../integrations/twitchSpade.js";
+const SPADE_PATTERN = /"(?:beacon|spade)_?url":\s*"(https:\/\/[.\w\-/]+\.ts(?:\?allow_stream=true)?)"/i;
+test("buildSpadePayload returns base64 data with minute-watched event", () => {
+    const out = buildSpadePayload("12345", "67890", "streamer", "user1");
+    assert.ok(out.data);
+    const decoded = Buffer.from(out.data, "base64").toString("utf8");
+    const payload = JSON.parse(decoded);
+    assert.equal(Array.isArray(payload), true);
+    assert.equal(payload[0]?.event, "minute-watched");
+    assert.equal(payload[0]?.properties?.broadcast_id, "12345");
+    assert.equal(payload[0]?.properties?.channel_id, "67890");
+    assert.equal(payload[0]?.properties?.channel, "streamer");
+    assert.equal(payload[0]?.properties?.user_id, "user1");
+    assert.equal(payload[0]?.properties?.live, true);
+    assert.equal(payload[0]?.properties?.player, "site");
+});
+test("spade URL regex extracts URL from synthetic HTML", () => {
+    const html = '"beacon_url": "https://spade.example.com/v1/beacon.ts?allow_stream=true"';
+    const match = html.match(SPADE_PATTERN);
+    assert.ok(match);
+    assert.equal(match[1], "https://spade.example.com/v1/beacon.ts?allow_stream=true");
+});

package/docs/ops/authentication.md

@@ -0,0 +1,32 @@
+## Authentication (headless)
+
+### Device-code login (recommended)
+
+```bash
+tdm auth login --no-open
+```
+
+Follow the printed `verification_uri` and `user_code` on another device.
+
+### Import an existing token
+
+```bash
+tdm auth import --token "auth-token=XXXX"
+# or
+tdm auth import --token-file /secure/path/token.txt
+```
+
+### Import cookies
+
+```bash
+tdm auth import-cookie --cookie "auth-token=XXXX; other=YYY"
+# or
+tdm auth import-cookie --cookie-file /secure/path/cookies.txt
+```
+
+### Validate
+
+```bash
+tdm auth validate
+```
+

package/docs/ops/drops-validation.md

@@ -0,0 +1,73 @@
+# Drops validation playbook
+
+This playbook helps confirm that the CLI actually advances and claims Twitch Drops as intended, without opening a browser stream.
+
+## Prerequisites
+
+- A Twitch account (test account recommended).
+- CLI installed and built: `npm run build`.
+- Auth completed: `tdm auth login --no-open` (or paste token when prompted).
+
+## 1. Configure for a single game
+
+- Choose an active Drops campaign with a **short first drop** (e.g. 15–30 minutes) so you can see progress quickly.
+- In config (e.g. `~/.config/tdm/config.json` or project `tdm.config.json`), set:
+  - `priority`: `["<Game Name>"]` (exact game name from the campaign).
+  - `priorityMode`: `"priority_only"` so only that game is mined.
+  - `exclude`: `[]` (or leave default).
+
+## 2. Dry run (no network writes)
+
+- Run with dry-run and verbose to see intended actions only:
+  ```bash
+  tdm run --dry-run --verbose
+  ```
+- Confirm logs show:
+  - Inventory fetch and campaign list.
+  - Wanted games = your priority game.
+  - Channel fetch and selected channel.
+  - “Would send watch” (no real spade POST).
+  - “Would claim” for any claimable drop (no real ClaimDrop GQL).
+- Stop with Ctrl+C.
+
+## 3. Live run and Twitch Inventory check
+
+- In a browser, open [Twitch Drops Inventory](https://www.twitch.tv/drops/inventory) and log in with the same account.
+- Note the current “minutes watched” (and “Claim” button if the drop is ready) for the target campaign.
+- Start the miner:
+  ```bash
+  tdm run --verbose
+  ```
+- Let it run for at least one watch interval (about 1 minute). You should see “Watch tick sent for channel …” in the logs.
+- Refresh the Twitch Inventory page: “minutes watched” for the active drop should increase (may take 1–2 minutes to reflect).
+- If the drop becomes claimable, the CLI should auto-claim; check logs for “Claimed drop” and confirm the drop shows as claimed in the Inventory.
+
+## 4. Compare with Python miner (optional)
+
+- Using the same Twitch account and same priority game:
+  - Run the Python TwitchDropsMiner and note progression/claim time.
+  - Run the CLI with the same config and note progression/claim time.
+- Progression and claim times should be comparable (allow for Twitch-side variance).
+
+## 5. Status command
+
+- While the miner is running (or after it has run), in another terminal:
+  ```bash
+  tdm status
+  tdm status --json
+  ```
+- Confirm `state` (e.g. WATCHING or MAINTENANCE) and `activeDrop` (e.g. “Game Name: Drop Name”) look correct.
+
+## Success criteria
+
+- With a test account and active drops campaign:
+  - `tdm run` increases “minutes watched” for the targeted drop on Twitch Inventory without opening a stream in the browser.
+  - Drops are claimed automatically when eligible (or a manual step is documented).
+  - `tdm run --dry-run --verbose` logs intended watch and claim actions without performing spade/claim network calls.
+  - `tdm status` shows a sensible state and active drop.
+
+## Troubleshooting
+
+- **No channels / “No channel candidates”**: Ensure the game has live streams with Drops enabled; try a different game or relax `priorityMode`.
+- **Watch tick failed**: Spade URL extraction or auth may be failing; run with `--verbose` and check logs.
+- **Minutes not updating**: Twitch can delay updates; wait 2–3 minutes and refresh the Inventory page. Ensure you’re watching a channel that has Drops for that campaign.

package/docs/ops/linux-install.md

@@ -0,0 +1,15 @@
+## Linux install (headless)
+
+- **Prereqs**: `node >= 20`, outbound HTTPS/WSS to Twitch.
+- Install globally:
+
+```bash
+npm install -g twitchdropsminer-cli
+```
+
+- Verify environment:
+
+```bash
+tdm doctor
+```
+

package/docs/ops/service-management.md

@@ -0,0 +1,23 @@
+## Running as a service (systemd)
+
+### Install user-level service
+
+```bash
+tdm service install --user --autostart
+tdm service start
+```
+
+### Check status
+
+```bash
+tdm service status
+```
+
+### Logs (journalctl)
+
+Use standard `journalctl` commands, e.g.:
+
+```bash
+journalctl --user -u tdm.service -f
+```
+

package/docs/ops/systemd-hardening.md

@@ -0,0 +1,13 @@
+## systemd hardening notes
+
+Recommended service-level settings:
+
+- `NoNewPrivileges=true`
+- `PrivateTmp=true`
+- `Restart=on-failure`
+- `RestartSec=5`
+- `After=network-online.target`
+- `Wants=network-online.target`
+
+Use user-level units for least privilege unless you explicitly need a system unit.
+

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "twitchdropsminer-cli",
+  "version": "0.1.0",
+  "description": "Headless CLI rewrite of DevilXD/TwitchDropsMiner for mining Twitch drops on servers.",
+  "bin": {
+    "tdm": "dist/cli/index.js"
+  },
+  "main": "dist/cli/index.js",
+  "files": [
+    "dist",
+    "docs/ops",
+    "resources/systemd"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "dev": "ts-node src/cli/index.ts",
+    "lint": "echo \"no linter configured\"",
+    "test": "npm run build && node --test dist/tests/index.js"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@commander-js/extra-typings": "^12.1.0",
+    "pino": "^9.0.0",
+    "tough-cookie": "^5.0.0",
+    "undici": "^6.0.0",
+    "ws": "^8.17.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.7.0"
+  }
+}

package/resources/systemd/tdm.service.tpl

@@ -0,0 +1,17 @@
+[Unit]
+Description=Twitch Drops Miner CLI
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart={{NODE_PATH}} {{TDM_BIN}} run
+Restart=on-failure
+RestartSec=5
+NoNewPrivileges=true
+PrivateTmp=true
+Environment=TDM_LOG_LEVEL=info
+
+[Install]
+WantedBy=default.target
+