TypeScript SDK

Installation

npm install @botnexus/sdk

npm install git+https://github.com/master00J/botnexus.git#main:packages/sdk

Requires Node.js 18+ (native fetch).

Basic usage

import { createBotNexusClient } from '@botnexus/sdk';

const client = createBotNexusClient({
  botId: process.env.BOTNEXUS_BOT_ID!,
  token: process.env.BOTNEXUS_API_TOKEN!,
  baseUrl: 'https://www.rsdash.net',
});

await client.pushStats({ platform: 'discord', server_count: 150 });
const { voted } = await client.checkVote({ platform: 'discord', userId: '80351110224678912' });

Client methods

• health() — GET /api/health
• getBot(id?) — public listing JSON
• searchBots(params) — public search
• getReviews(id?) — public reviews
• pushStats(input) — POST stats
• updateStatus(input) — PUT runtime status
• syncCommands(input) — PUT command list
• checkVote(input) — GET vote check
• listVotes(params) — GET paginated votes
• getStatsHistory(params) — GET stats history
• getAnalytics() — GET owner analytics
• pushStatsBulk({ updates }) — POST multi-platform stats
• getAnnouncements(id?) — GET active announcements
• getWidget(id?) — GET compact embed JSON
• postAnnouncement(input) — POST listing announcement
• listWebhooks() — GET configured webhooks (no secrets)
• createWebhook(input) — POST new webhook
• updateWebhook(input) — PATCH webhook settings
• deleteWebhook(webhookId) — DELETE webhook
• testWebhook({ webhook_id }) — POST test delivery
• listWebhookDeliveries({ webhook_id }) — GET delivery log
• rotateWebhookSecret({ webhook_id }) — POST rotate signing secret
• getChangelog(id?) — GET public changelog
• createChangelogEntry(input) — POST changelog entry
• updateChangelogEntry(input) — PATCH changelog entry
• deleteChangelogEntry(entryId) — DELETE changelog entry

Options & reliability

• timeoutMs — request timeout (default 15s)
• maxRetries — retries on 429/5xx for GETs (default 2)
• circuitBreakerThreshold — consecutive failures before pausing (default 5, 0 = off)
• circuitBreakerResetMs — how long the circuit stays open (default 60s)
• debug — log requests to console
• onRequest / onResponse — interceptors for logging

const client = createBotNexusClient({
  botId: '…',
  token: '…',
  timeoutMs: 10_000,
  maxRetries: 3,
  onResponse: ({ status, durationMs }) => console.log(status, durationMs),
});

Webhook verification

Verify inbound BotNexus webhooks on your server:

import { BotNexusWebhook } from '@botnexus/sdk';

const valid = BotNexusWebhook.verify({
  secret: process.env.WEBHOOK_SECRET!,
  rawBody: req.rawBody,
  timestamp: req.headers['x-botnexus-timestamp'],
  signature: req.headers['x-botnexus-signature'],
});

Utilities & types

• BotNexusError — status, code, retryAfterMs, body
• isWebhookPayload() — runtime type guard
• getDiscordId(identities) — extract Discord snowflake
• formatVoteCooldown() — human-readable cooldown
• All request/response interfaces are exported from the package