MarzbanSDK

The complete TypeScript SDK for the Marzban API.

Typed endpoints, auto token refresh, retries, WebSocket log streaming, webhooks and runtime validation — isomorphic for Node.js and the browser.

Documentation · Quick Start · API Reference

marzban-sdk is far more than an API client. It bundles the entire infrastructure layer a serious Marzban integration needs — so you ship features, not plumbing. Every endpoint, parameter and response is generated from the official OpenAPI spec and fully typed, with autocomplete across the whole API.

Install

npm install marzban-sdk

Also works with pnpm add, yarn add, or bun add.

Quick start

import { createMarzbanSDK, isAuthError } from 'marzban-sdk'

// One call authenticates and wires up every API module.
// Token refresh and retries are handled for you.
const sdk = await createMarzbanSDK({
  baseUrl: 'https://panel.example.com',
  username: 'admin',
  password: 'secret',
})

// Fully typed API surface: users · nodes · system · subscriptions · …
const { users } = await sdk.user.getUsers({ status: 'active', limit: 10 })
const stats = await sdk.system.getSystemStats()

// Stream real-time logs from the core over WebSocket
const close = await sdk.logs.connectByCore({
  onMessage: data => console.log(data),
})

// Typed, narrowable error handling
try {
  await sdk.user.getUser('does-not-exist')
} catch (err) {
  if (isAuthError(err)) await sdk.authorize()
}

Features

• 🔠 End-to-end type safety — every endpoint, parameter and response is fully typed, generated straight from the official OpenAPI spec. Matching Zod schemas ship alongside every model.
• 🌐 Truly cross-runtime — one package, one identical API across 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 — dual ESM + CJS bundle, side-effect free and fully tree-shakeable, so you ship only what you use.
• 🔑 Flexible authentication — log in on init, hand the SDK an existing JWT, or take full manual control; expired sessions refresh transparently on 401, so your code never touches a token.
• 🔁 Built-in resilience — configurable exponential back-off for transient network failures, plus automatic WebSocket reconnects.
• 🎯 Classified errors — AuthError, HttpError, ConfigurationError and webhook errors all extend SdkError with a machine-readable code and type-guard helpers for precise handling.
• 🛡️ Runtime validation — config and payloads validated with Zod; misconfigured clients fail fast with readable details.
• 📡 Real-time logs — stream live core and node logs over WebSocket, with auto token refresh and reconnection.
• 📨 Webhooks included — HMAC-SHA256 signature verification, typed event subscriptions, wildcard handlers and batch processing.
• 🛠️ Batteries-included utilities — first-class helpers for data-size conversion, datetime math and subscription template variables.

API modules

| Module | Access | What it does | | -------------- | ------------------ | --------------------------------------------------------- | | Users | sdk.user | Create, update, reset and inspect users and their traffic | | Nodes | sdk.node | Add, configure and monitor connected nodes | | System | sdk.system | Live stats, inbounds and proxy host config | | Core | sdk.core | Read config, restart and control the Xray core | | Subscriptions | sdk.subscription | Resolve subscription links and per-client configs | | User templates | sdk.userTemplate | Reusable templates for provisioning users | | Admins | sdk.admin | Manage admin accounts and permissions | | Logs | sdk.logs | WebSocket log streams from the core and nodes | | Webhooks | sdk.webhook | Verify and handle inbound Marzban events |

Documentation

Full guides, configuration reference and the complete typed API live at ilmar7786.github.io/marzban-sdk:

• Installation & Quick Start
• Configuration options
• Error handling & validation
• Webhooks & WebSocket logs
• Utilities

Contributing

Contributions are welcome — see CONTRIBUTING.md. Found a bug or have an idea? Open an issue.

License

MIT © ilmar7786