Introduction

MarzbanSDK is a complete, production-grade TypeScript SDK for building Marzban integrations. Beyond fully typed coverage of the entire API, it bundles the infrastructure a real integration needs — authentication with transparent token refresh, retries, WebSocket log streaming, webhook verification, and runtime validation — and behaves identically in Node.js, Bun, Deno, and the browser.

Features

• First-class TypeScript — every request, response, and error is fully typed, generated directly from the Marzban OpenAPI specification. Matching Zod schemas are exported alongside every model.
• Truly cross-runtime — the same API in Node.js, Bun, Deno, and the browser: native WebSocket and the Web Crypto API where available, with a transparent ws fallback for older Node.js.
• Modern build — a dual ESM + CJS bundle, side-effect free and fully tree-shakeable, so you ship only what you use.
• Flexible authentication — log in automatically on startup, pass an existing JWT, or take full manual control; expired sessions refresh transparently on 401, so your code never touches a token.
• Built-in resilience — exponential-backoff retries with a configurable retry count, plus automatic WebSocket reconnects.
• Classified error system — AuthError, HttpError, ConfigurationError, and webhook errors all extend SdkError with a machine-readable code and type-guard helpers.
• Runtime validation — config and all API responses are validated with Zod. Bad data is caught immediately with structured error details.
• Real-time log streaming — sdk.logs streams core and node logs over WebSocket with automatic token refresh and configurable reconnection.
• Webhooks — sdk.webhook handles incoming Marzban events with HMAC-SHA256 signature verification, typed event subscriptions, wildcard listeners, and batch processing.
• Batteries-included utilities — first-class helpers for data-size formatting/parsing, datetime calculations, and template variables.

Module overview

Quick example

import { createMarzbanSDK, formatBytes, humanRemaining } from 'marzban-sdk'

const sdk = await createMarzbanSDK({
  baseUrl: 'https://vpn.example.com',
  username: 'admin',
  password: 'secret',
})

// List active users
const { users, total } = await sdk.user.getUsers({ status: 'active' })
console.log(`${total} active users`)

for (const user of users) {
  const dataLeft = formatBytes((user.data_limit ?? 0) - user.used_traffic)
  const timeLeft = user.expire ? humanRemaining(user.expire * 1000) : '∞'
  console.log(`${user.username} — ${dataLeft} left, expires ${timeLeft}`)
}