perp-cli 0.5.3 → 0.6.1

package/dist/commands/history.js

@@ -1,6 +1,7 @@
 import chalk from "chalk";
 import { printJson, jsonOk, jsonError, makeTable, formatUsd, formatPnl, withJsonErrors } from "../utils.js";
 import { readExecutionLog, getExecutionStats, pruneExecutionLog } from "../execution-log.js";
+import { loadArbState } from "../arb/state.js";
 import { readPositionHistory, getPositionStats } from "../position-history.js";
 import { saveEquitySnapshot, readEquityHistory, computePnlMetrics, computeDailyPnl, aggregateWeekly, } from "../equity-tracker.js";
 const EXCHANGES = ["pacifica", "hyperliquid", "lighter"];
@@ -15,6 +16,17 @@ function parseSince(since) {
     }
     return since;
 }
+/** Parse period string (7d, 30d, 90d) to milliseconds. Returns undefined for "all" or missing. */
+function parsePeriodMs(period) {
+    if (!period || period === "all")
+        return undefined;
+    const match = period.match(/^(\d+)(h|d|w|m)$/);
+    if (!match)
+        return undefined;
+    const [, num, unit] = match;
+    const ms = { h: 3600000, d: 86400000, w: 604800000, m: 2592000000 }[unit] ?? 86400000;
+    return parseInt(num) * ms;
+}
 export function registerHistoryCommands(program, isJson, getAdapterForExchange) {
     const history = program.command("history").description("Execution log & audit trail");
     // ── history list ──
@@ -314,158 +326,281 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
     // ── analytics pnl ──
     parent
         .command("pnl")
-        .description("Realized P&L from exchange trade history (volume & fees by symbol/exchange)")
+        .description("P&L analysis — trades, fees, funding income with daily breakdown")
         .option("-e, --exchange <exchanges>", "Comma-separated exchanges")
-        .option("--since <period>", "Period: 24h, 7d, 30d")
-        .option("-n, --limit <n>", "Trade history limit per exchange", "100")
+        .option("--period <duration>", "Time period: 7d, 30d, 90d, all (default: all)")
+        .option("--since <period>", "Alias for --period")
+        .option("-n, --limit <n>", "History limit per exchange", "200")
         .action(async (opts) => {
         await withJsonErrors(isJson(), async () => {
             const exchanges = opts.exchange
                 ? opts.exchange.split(",").map(e => e.trim())
                 : [...EXCHANGES];
+            const period = opts.period ?? opts.since;
+            const periodMs = parsePeriodMs(period);
+            const sinceMs = periodMs ? Date.now() - periodMs : 0;
             const limit = parseInt(opts.limit);
-            const sinceMs = opts.since ? new Date(parseSince(opts.since)).getTime() : 0;
             const allTrades = [];
+            const allFunding = [];
+            // Fetch trades + funding in parallel from all exchanges
             await Promise.allSettled(exchanges.map(async (ex) => {
                 try {
                     const adapter = await getAdapterForExchange(ex);
-                    const trades = await adapter.getTradeHistory(limit);
+                    const [trades, funding] = await Promise.all([
+                        adapter.getTradeHistory(limit),
+                        adapter.getFundingPayments(limit),
+                    ]);
                     for (const t of trades) {
                         if (sinceMs && t.time < sinceMs)
                             continue;
-                        allTrades.push({
-                            exchange: ex,
-                            symbol: t.symbol,
-                            side: t.side,
-                            price: Number(t.price),
-                            size: Number(t.size),
-                            fee: Number(t.fee),
-                            time: t.time,
-                        });
+                        allTrades.push({ exchange: ex, symbol: t.symbol, side: t.side, price: Number(t.price), size: Number(t.size), fee: Number(t.fee), time: t.time });
+                    }
+                    for (const f of funding) {
+                        if (sinceMs && f.time < sinceMs)
+                            continue;
+                        allFunding.push({ exchange: ex, symbol: f.symbol, payment: Number(f.payment), time: f.time });
                     }
                 }
                 catch { /* skip unavailable exchanges */ }
             }));
-            // Aggregate by symbol
-            const bySymbol = new Map();
+            // Aggregate by exchange
             const byExchange = new Map();
             let totalVolume = 0;
             let totalFees = 0;
+            let totalFunding = 0;
             for (const t of allTrades) {
                 const notional = t.price * t.size;
                 totalVolume += notional;
                 totalFees += t.fee;
-                const sym = bySymbol.get(t.symbol) ?? { volume: 0, fees: 0, trades: 0 };
-                sym.volume += notional;
-                sym.fees += t.fee;
-                sym.trades++;
-                bySymbol.set(t.symbol, sym);
-                const ex = byExchange.get(t.exchange) ?? { volume: 0, fees: 0, trades: 0 };
+                const ex = byExchange.get(t.exchange) ?? { trades: 0, volume: 0, fees: 0, funding: 0 };
+                ex.trades++;
                 ex.volume += notional;
                 ex.fees += t.fee;
-                ex.trades++;
                 byExchange.set(t.exchange, ex);
             }
+            for (const f of allFunding) {
+                totalFunding += f.payment;
+                const ex = byExchange.get(f.exchange) ?? { trades: 0, volume: 0, fees: 0, funding: 0 };
+                ex.funding += f.payment;
+                byExchange.set(f.exchange, ex);
+            }
+            const netPnl = totalFunding - totalFees;
+            // Daily PnL breakdown (fees + funding combined)
+            const dailyMap = new Map();
+            for (const t of allTrades) {
+                const day = new Date(t.time).toISOString().slice(0, 10);
+                const d = dailyMap.get(day) ?? { fees: 0, funding: 0 };
+                d.fees += t.fee;
+                dailyMap.set(day, d);
+            }
+            for (const f of allFunding) {
+                const day = new Date(f.time).toISOString().slice(0, 10);
+                const d = dailyMap.get(day) ?? { fees: 0, funding: 0 };
+                d.funding += f.payment;
+                dailyMap.set(day, d);
+            }
+            const daily = [...dailyMap.entries()]
+                .sort()
+                .map(([date, d]) => ({ date, fees: d.fees, funding: d.funding, net: d.funding - d.fees }));
             const result = {
+                period: period ?? "all",
                 totalTrades: allTrades.length,
                 totalVolume,
                 totalFees,
-                netAfterFees: -totalFees, // realized PnL would need entry/exit matching; fees are definite cost
-                bySymbol: Object.fromEntries(bySymbol),
-                byExchange: Object.fromEntries(byExchange),
+                totalFunding,
+                netPnl,
+                byExchange: Object.fromEntries([...byExchange.entries()].map(([ex, d]) => [ex, { ...d, netPnl: d.funding - d.fees }])),
+                daily,
             };
             if (isJson())
                 return printJson(jsonOk(result));
-            console.log(chalk.cyan.bold(`\n  Realized Trading P&L ${opts.since ? `(${opts.since})` : ""}\n`));
+            // ── Terminal output ──
+            console.log(chalk.cyan.bold(`\n  P&L Report${period ? ` (${period})` : ""}\n`));
             console.log(`  Total Trades:    ${allTrades.length}`);
             console.log(`  Total Volume:    $${formatUsd(totalVolume)}`);
-            console.log(`  Total Fees:      ${chalk.red(`-$${formatUsd(totalFees)}`)}`);
-            if (bySymbol.size > 0) {
-                console.log(chalk.white.bold("\n  By Symbol:"));
-                const symRows = [...bySymbol.entries()]
-                    .sort((a, b) => b[1].volume - a[1].volume)
-                    .map(([sym, d]) => [
-                    chalk.white.bold(sym),
-                    String(d.trades),
-                    `$${formatUsd(d.volume)}`,
-                    chalk.red(`-$${formatUsd(d.fees)}`),
-                ]);
-                console.log(makeTable(["Symbol", "Trades", "Volume", "Fees"], symRows));
-            }
+            console.log(`  Trading Fees:    ${chalk.red(`-$${formatUsd(totalFees)}`)}`);
+            console.log(`  Funding Income:  ${formatPnl(totalFunding)}`);
+            console.log(`  Net P&L:         ${formatPnl(netPnl)}`);
             if (byExchange.size > 0) {
-                console.log(chalk.white.bold("  By Exchange:"));
-                const exRows = [...byExchange.entries()].map(([ex, d]) => [
+                console.log(chalk.white.bold("\n  By Exchange:"));
+                const rows = [...byExchange.entries()].map(([ex, d]) => [
                     chalk.white.bold(ex),
                     String(d.trades),
                     `$${formatUsd(d.volume)}`,
                     chalk.red(`-$${formatUsd(d.fees)}`),
+                    formatPnl(d.funding),
+                    formatPnl(d.funding - d.fees),
                 ]);
-                console.log(makeTable(["Exchange", "Trades", "Volume", "Fees"], exRows));
+                console.log(makeTable(["Exchange", "Trades", "Volume", "Fees", "Funding", "Net P&L"], rows));
+            }
+            if (daily.length > 0) {
+                console.log(chalk.white.bold("  Daily P&L:"));
+                let cumulative = 0;
+                const rows = daily.map(d => {
+                    cumulative += d.net;
+                    return [d.date, chalk.red(`-$${formatUsd(d.fees)}`), formatPnl(d.funding), formatPnl(d.net), formatPnl(cumulative)];
+                });
+                console.log(makeTable(["Date", "Fees", "Funding", "Net", "Cumulative"], rows));
             }
         });
     });
     // ── analytics funding ──
     parent
         .command("funding")
-        .description("Funding payment aggregation across exchanges (net by symbol/exchange)")
+        .description("Funding income analysis — cumulative, daily, per-arb-position breakdown")
         .option("-e, --exchange <exchanges>", "Comma-separated exchanges")
         .option("-s, --symbol <symbol>", "Filter by symbol")
-        .option("-n, --limit <n>", "Funding history limit per exchange", "50")
+        .option("--period <duration>", "Time period: 7d, 30d, 90d, all (default: all)")
+        .option("--daily", "Show daily funding breakdown")
+        .option("-n, --limit <n>", "Funding history limit per exchange", "200")
         .action(async (opts) => {
         await withJsonErrors(isJson(), async () => {
             const exchanges = opts.exchange
                 ? opts.exchange.split(",").map(e => e.trim())
                 : [...EXCHANGES];
+            const periodMs = parsePeriodMs(opts.period);
+            const sinceMs = periodMs ? Date.now() - periodMs : 0;
             const allFunding = [];
+            // Fetch funding payments and current positions in parallel
+            const positionNotionals = new Map();
             await Promise.allSettled(exchanges.map(async (ex) => {
                 try {
                     const adapter = await getAdapterForExchange(ex);
-                    const payments = await adapter.getFundingPayments(parseInt(opts.limit));
+                    const [payments, positions] = await Promise.all([
+                        adapter.getFundingPayments(parseInt(opts.limit)),
+                        adapter.getPositions(),
+                    ]);
                     for (const p of payments) {
+                        if (sinceMs && p.time < sinceMs)
+                            continue;
                         if (opts.symbol && !p.symbol.toUpperCase().includes(opts.symbol.toUpperCase()))
                             continue;
-                        allFunding.push({
-                            exchange: ex,
-                            symbol: p.symbol,
-                            payment: Number(p.payment),
-                            time: p.time,
-                        });
+                        allFunding.push({ exchange: ex, symbol: p.symbol, payment: Number(p.payment), time: p.time });
+                    }
+                    for (const p of positions) {
+                        if (Number(p.size) > 0) {
+                            positionNotionals.set(`${ex}:${p.symbol}`, Math.abs(Number(p.size) * Number(p.markPrice)));
+                        }
                     }
                 }
-                catch { /* skip */ }
+                catch { /* skip unavailable exchanges */ }
             }));
-            // Aggregate
-            const bySymbol = new Map();
+            allFunding.sort((a, b) => a.time - b.time);
+            // Aggregate by exchange×symbol
+            const byExSym = new Map();
             const byExchange = new Map();
             let totalFunding = 0;
             for (const f of allFunding) {
                 totalFunding += f.payment;
-                bySymbol.set(f.symbol, (bySymbol.get(f.symbol) ?? 0) + f.payment);
+                const key = `${f.exchange}:${f.symbol}`;
+                const entry = byExSym.get(key) ?? { exchange: f.exchange, symbol: f.symbol, total: 0, count: 0 };
+                entry.total += f.payment;
+                entry.count++;
+                byExSym.set(key, entry);
                 byExchange.set(f.exchange, (byExchange.get(f.exchange) ?? 0) + f.payment);
             }
+            // Period days for annualized rate
+            const periodDays = periodMs
+                ? periodMs / 86400000
+                : allFunding.length > 1
+                    ? (allFunding[allFunding.length - 1].time - allFunding[0].time) / 86400000
+                    : 1;
+            // Match funding to arb positions
+            const arbState = loadArbState();
+            const arbPositions = arbState?.positions ?? [];
+            const arbFunding = new Map();
+            for (const pos of arbPositions) {
+                arbFunding.set(pos.symbol, { longFunding: 0, shortFunding: 0 });
+            }
+            for (const f of allFunding) {
+                const arbEntry = arbFunding.get(f.symbol);
+                if (!arbEntry)
+                    continue;
+                const pos = arbPositions.find(p => p.symbol === f.symbol);
+                if (f.exchange === pos.longExchange)
+                    arbEntry.longFunding += f.payment;
+                else if (f.exchange === pos.shortExchange)
+                    arbEntry.shortFunding += f.payment;
+            }
+            // Daily breakdown
+            const dailyMap = new Map();
+            for (const f of allFunding) {
+                const day = new Date(f.time).toISOString().slice(0, 10);
+                dailyMap.set(day, (dailyMap.get(day) ?? 0) + f.payment);
+            }
+            // Build result
+            const exSymRows = [...byExSym.values()].sort((a, b) => b.total - a.total).map(e => {
+                const notional = positionNotionals.get(`${e.exchange}:${e.symbol}`);
+                const annRate = notional && notional > 0 && periodDays > 0
+                    ? (e.total / Math.max(1, periodDays)) * 365 / notional * 100
+                    : null;
+                return { exchange: e.exchange, symbol: e.symbol, total: e.total, count: e.count, annualizedRate: annRate };
+            });
+            const arbRows = arbPositions
+                .map(pos => {
+                const af = arbFunding.get(pos.symbol);
+                if (!af || (af.longFunding === 0 && af.shortFunding === 0))
+                    return null;
+                return {
+                    symbol: pos.symbol,
+                    mode: pos.mode ?? "perp-perp",
+                    longExchange: pos.longExchange,
+                    shortExchange: pos.shortExchange,
+                    netFunding: af.longFunding + af.shortFunding,
+                    longFunding: af.longFunding,
+                    shortFunding: af.shortFunding,
+                    daysSinceEntry: Math.max(1, Math.round((Date.now() - new Date(pos.entryTime).getTime()) / 86400000)),
+                };
+            })
+                .filter((r) => r !== null);
+            const daily = [...dailyMap.entries()].sort().map(([date, amount]) => ({ date, amount }));
             const result = {
-                totalPayments: allFunding.length,
+                period: opts.period ?? "all",
+                periodDays: Math.max(1, Math.round(periodDays)),
                 totalFunding,
-                bySymbol: Object.fromEntries(bySymbol),
+                totalPayments: allFunding.length,
+                byExchangeSymbol: exSymRows,
                 byExchange: Object.fromEntries(byExchange),
+                arbPositions: arbRows,
+                ...(opts.daily ? { daily } : {}),
             };
             if (isJson())
                 return printJson(jsonOk(result));
-            console.log(chalk.cyan.bold("\n  Funding Payment Summary\n"));
+            // ── Terminal output ──
+            console.log(chalk.cyan.bold(`\n  Funding Income Report${opts.period ? ` (${opts.period})` : ""}\n`));
             console.log(`  Total Payments:  ${allFunding.length}`);
             console.log(`  Net Funding:     ${formatPnl(totalFunding)}`);
-            if (bySymbol.size > 0) {
-                console.log(chalk.white.bold("\n  By Symbol:"));
-                const rows = [...bySymbol.entries()]
-                    .sort((a, b) => b[1] - a[1])
-                    .map(([sym, amt]) => [chalk.white.bold(sym), formatPnl(amt)]);
-                console.log(makeTable(["Symbol", "Net Funding"], rows));
+            console.log(`  Period:          ~${Math.round(periodDays)} days`);
+            if (exSymRows.length > 0) {
+                console.log(chalk.white.bold("\n  By Exchange × Symbol:"));
+                const rows = exSymRows.map(e => [
+                    chalk.white.bold(e.exchange),
+                    e.symbol,
+                    formatPnl(e.total),
+                    String(e.count),
+                    e.annualizedRate !== null ? `${e.annualizedRate >= 0 ? "+" : ""}${e.annualizedRate.toFixed(1)}%` : chalk.gray("—"),
+                ]);
+                console.log(makeTable(["Exchange", "Symbol", "Total", "Payments", "Ann.Rate"], rows));
             }
-            if (byExchange.size > 0) {
-                console.log(chalk.white.bold("  By Exchange:"));
-                const rows = [...byExchange.entries()]
-                    .map(([ex, amt]) => [chalk.white.bold(ex), formatPnl(amt)]);
-                console.log(makeTable(["Exchange", "Net Funding"], rows));
+            if (arbRows.length > 0) {
+                console.log(chalk.white.bold("  By Arb Position:"));
+                const rows = arbRows.map(a => [
+                    chalk.white.bold(a.symbol),
+                    `${a.longExchange} → ${a.shortExchange}`,
+                    a.mode,
+                    formatPnl(a.netFunding),
+                    `${a.daysSinceEntry}d`,
+                ]);
+                console.log(makeTable(["Symbol", "Long → Short", "Mode", "Net Funding", "Held"], rows));
+            }
+            if (opts.daily && daily.length > 0) {
+                console.log(chalk.white.bold("  Daily Breakdown:"));
+                let cumulative = 0;
+                const rows = daily.map(d => {
+                    cumulative += d.amount;
+                    return [d.date, formatPnl(d.amount), formatPnl(cumulative)];
+                });
+                console.log(makeTable(["Date", "Funding", "Cumulative"], rows));
             }
         });
     });
@@ -558,6 +693,130 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
             console.log();
         });
     });
+    // ── analytics compare ──
+    parent
+        .command("compare")
+        .description("Compare active arb positions — ROI, realized PnL, funding income side by side")
+        .option("--period <duration>", "Funding lookup period: 7d, 30d, 90d, all (default: all)")
+        .option("-n, --limit <n>", "Funding history limit per exchange", "200")
+        .action(async (opts) => {
+        await withJsonErrors(isJson(), async () => {
+            const arbState = loadArbState();
+            const positions = arbState?.positions ?? [];
+            if (positions.length === 0) {
+                if (isJson())
+                    return printJson(jsonOk({ positions: [], message: "No active arb positions" }));
+                console.log(chalk.yellow("\n  No active arb positions. Use 'perp arb exec' to open one.\n"));
+                return;
+            }
+            const periodMs = parsePeriodMs(opts.period);
+            const sinceMs = periodMs ? Date.now() - periodMs : 0;
+            const limit = parseInt(opts.limit);
+            // Collect all unique exchanges from arb positions
+            const exchangeSet = new Set();
+            for (const pos of positions) {
+                exchangeSet.add(pos.longExchange);
+                exchangeSet.add(pos.shortExchange);
+            }
+            // Fetch funding + current positions from all relevant exchanges
+            const fundingByExSym = new Map();
+            const currentPrices = new Map();
+            await Promise.allSettled([...exchangeSet].map(async (ex) => {
+                try {
+                    const adapter = await getAdapterForExchange(ex);
+                    const [funding, livePositions] = await Promise.all([
+                        adapter.getFundingPayments(limit),
+                        adapter.getPositions(),
+                    ]);
+                    for (const f of funding) {
+                        if (sinceMs && f.time < sinceMs)
+                            continue;
+                        const key = `${ex}:${f.symbol}`;
+                        fundingByExSym.set(key, (fundingByExSym.get(key) ?? 0) + Number(f.payment));
+                    }
+                    for (const p of livePositions) {
+                        currentPrices.set(`${ex}:${p.symbol}`, Number(p.markPrice));
+                    }
+                }
+                catch { /* skip */ }
+            }));
+            // Build comparison data
+            const rows = positions.map(pos => {
+                const daysHeld = Math.max(1, Math.round((Date.now() - new Date(pos.entryTime).getTime()) / 86400000));
+                const longFunding = fundingByExSym.get(`${pos.longExchange}:${pos.symbol}`) ?? 0;
+                const shortFunding = fundingByExSym.get(`${pos.shortExchange}:${pos.symbol}`) ?? 0;
+                const netFunding = longFunding + shortFunding;
+                // Estimate unrealized PnL from price movement
+                const longPrice = currentPrices.get(`${pos.longExchange}:${pos.symbol}`) ?? pos.entryLongPrice;
+                const shortPrice = currentPrices.get(`${pos.shortExchange}:${pos.symbol}`) ?? pos.entryShortPrice;
+                const longPnl = (longPrice - pos.entryLongPrice) * pos.longSize;
+                const shortPnl = (pos.entryShortPrice - shortPrice) * pos.shortSize;
+                const pricePnl = longPnl + shortPnl;
+                const totalPnl = pricePnl + netFunding;
+                // Notional for ROI calculation
+                const notional = pos.entryLongPrice * pos.longSize + pos.entryShortPrice * pos.shortSize;
+                const roi = notional > 0 ? (totalPnl / notional) * 100 : 0;
+                const fundingRoi = notional > 0 ? (netFunding / notional) * 100 : 0;
+                const annualizedRoi = daysHeld > 0 ? (fundingRoi / daysHeld) * 365 : 0;
+                return {
+                    symbol: pos.symbol,
+                    mode: pos.mode ?? "perp-perp",
+                    longExchange: pos.longExchange,
+                    shortExchange: pos.shortExchange,
+                    daysHeld,
+                    entrySpread: pos.entrySpread,
+                    funding: netFunding,
+                    pricePnl,
+                    totalPnl,
+                    notional,
+                    roi,
+                    fundingRoi,
+                    annualizedRoi,
+                };
+            });
+            // Sort by total PnL descending
+            rows.sort((a, b) => b.totalPnl - a.totalPnl);
+            const totals = {
+                funding: rows.reduce((s, r) => s + r.funding, 0),
+                pricePnl: rows.reduce((s, r) => s + r.pricePnl, 0),
+                totalPnl: rows.reduce((s, r) => s + r.totalPnl, 0),
+                notional: rows.reduce((s, r) => s + r.notional, 0),
+            };
+            const result = {
+                period: opts.period ?? "all",
+                positionCount: rows.length,
+                positions: rows,
+                totals: {
+                    ...totals,
+                    roi: totals.notional > 0 ? (totals.totalPnl / totals.notional) * 100 : 0,
+                },
+            };
+            if (isJson())
+                return printJson(jsonOk(result));
+            // ── Terminal output ──
+            console.log(chalk.cyan.bold(`\n  Arb Position Comparison${opts.period ? ` (${opts.period})` : ""}\n`));
+            const tableRows = rows.map(r => [
+                chalk.white.bold(r.symbol),
+                `${r.longExchange} → ${r.shortExchange}`,
+                r.mode,
+                `${r.daysHeld}d`,
+                formatPnl(r.funding),
+                formatPnl(r.pricePnl),
+                formatPnl(r.totalPnl),
+                `${r.roi >= 0 ? "+" : ""}${r.roi.toFixed(2)}%`,
+                `${r.annualizedRoi >= 0 ? "+" : ""}${r.annualizedRoi.toFixed(1)}%`,
+            ]);
+            console.log(makeTable(["Symbol", "Long → Short", "Mode", "Held", "Funding", "Price PnL", "Total PnL", "ROI", "Ann.ROI"], tableRows));
+            console.log(chalk.white.bold("  Totals:"));
+            console.log(`    Funding Income:   ${formatPnl(totals.funding)}`);
+            console.log(`    Price PnL:        ${formatPnl(totals.pricePnl)}`);
+            console.log(`    Total PnL:        ${formatPnl(totals.totalPnl)}`);
+            if (totals.notional > 0) {
+                console.log(`    Total ROI:        ${result.totals.roi >= 0 ? "+" : ""}${result.totals.roi.toFixed(2)}%`);
+            }
+            console.log();
+        });
+    });
 }
 function parseSinceDate(since) {
     if (!since)

package/dist/discord.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Discord Bot DM client.
+ *
+ * Sends direct messages to a user via the Discord Bot API (REST only, no gateway).
+ * Requires: bot token + user ID.
+ */
+export interface DiscordConfig {
+    botToken: string;
+    userId: string;
+    channelId?: string;
+}
+/**
+ * Open (or retrieve cached) DM channel with a user.
+ * Returns the channel ID for sending messages.
+ */
+export declare function openDMChannel(config: DiscordConfig): Promise<string>;
+/**
+ * Send a DM to the configured user.
+ * Automatically opens a DM channel if needed.
+ */
+export declare function sendDiscordDM(config: DiscordConfig, message: string): Promise<void>;
+/**
+ * Validate bot token by fetching bot user info.
+ * Returns the bot's username if valid.
+ */
+export declare function validateBotToken(token: string): Promise<{
+    valid: boolean;
+    username: string;
+}>;

package/dist/discord.js

@@ -0,0 +1,66 @@
+/**
+ * Discord Bot DM client.
+ *
+ * Sends direct messages to a user via the Discord Bot API (REST only, no gateway).
+ * Requires: bot token + user ID.
+ */
+const DISCORD_API = "https://discord.com/api/v10";
+/**
+ * Open (or retrieve cached) DM channel with a user.
+ * Returns the channel ID for sending messages.
+ */
+export async function openDMChannel(config) {
+    if (config.channelId)
+        return config.channelId;
+    const res = await fetch(`${DISCORD_API}/users/@me/channels`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bot ${config.botToken}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ recipient_id: config.userId }),
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`Discord DM channel failed (${res.status}): ${body}`);
+    }
+    const data = (await res.json());
+    return data.id;
+}
+/**
+ * Send a DM to the configured user.
+ * Automatically opens a DM channel if needed.
+ */
+export async function sendDiscordDM(config, message) {
+    const channelId = await openDMChannel(config);
+    const res = await fetch(`${DISCORD_API}/channels/${channelId}/messages`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bot ${config.botToken}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ content: message }),
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`Discord send failed (${res.status}): ${body}`);
+    }
+}
+/**
+ * Validate bot token by fetching bot user info.
+ * Returns the bot's username if valid.
+ */
+export async function validateBotToken(token) {
+    try {
+        const res = await fetch(`${DISCORD_API}/users/@me`, {
+            headers: { Authorization: `Bot ${token}` },
+        });
+        if (!res.ok)
+            return { valid: false, username: "" };
+        const data = (await res.json());
+        return { valid: true, username: `${data.username}#${data.discriminator}` };
+    }
+    catch {
+        return { valid: false, username: "" };
+    }
+}