TypeScript SDK

Official SDK

This SDK is official and maintained by the Remnawave team.

Remnawave TypeScript SDK is a library for convenient interaction with the RestAPI types.

It does not contain http-client, so you need to implement it yourself.

This SDK can be used in backend and frontend.

Installation

npm install @remnawave/backend-contract

warning

Always pick and pin the correct version of the SDK to match the version of the Remnawave backend.

Contract Version	Remnawave Panel Version
3.2.3	3.2.3
3.2.2	3.2.2
3.2.0	3.2.0 – 3.2.1
3.1.1	3.1.0
3.0.0	3.0.0
2.8.35	2.8.0 – 2.8.1
2.7.2	2.7.3 – 2.7.4
2.7.0	2.7.0 – 2.7.2
2.6.20	2.6.4
2.6.19	2.6.3
2.6.16	2.6.2
2.6.1	2.6.1
2.6.0	2.6.0
2.5.20	2.5.7
2.5.13	2.5.4 - 2.5.6
2.5.9	2.5.0 - 2.5.3
2.4.1	2.4.3 - 2.4.4
2.4.0	2.4.0 - 2.4.2
2.3.38	2.3.2
2.3.35	2.3.0 – 2.3.1
2.2.34	2.2.6
2.2.32	2.2.4 – 2.2.5
2.2.26	2.2.1 – 2.2.3
2.2.24	2.2.0
2.1.70	2.1.19
2.1.68	2.1.18
2.1.64	2.1.16
2.1.62	2.1.15
2.1.57	2.1.14
2.1.41	2.1.13
2.1.39	2.1.12
2.1.33	2.1.8 – 2.1.11
2.1.26	2.1.7
2.1.25	2.1.4 – 2.1.6
2.1.14	2.1.1 – 2.1.3
2.1.12	2.1.0
2.0.2	2.0.6 – 2.0.8
2.0.0	2.0.0 – 2.0.5

Usage

Example backend service, using Axios and NestJS

import axios from 'axios'

import { Injectable, Logger } from '@nestjs/common'
import { ConfigService } from '@nestjs/config'

import { GetUserByUsernameCommand } from '@remnawave/backend-contract'

import { ICommandResponse } from '../types/command-response.type'

@Injectable()
export class AxiosService {
  public axiosInstance: AxiosInstance
  private readonly logger = new Logger(AxiosService.name)

  constructor(private readonly configService: ConfigService) {
    this.axiosInstance = axios.create({
      baseURL: this.configService.getOrThrow('REMNAWAVE_PANEL_URL'),
      timeout: 45_000,
      headers: {
        'x-forwarded-for': '127.0.0.1', // use this headers to bypass the panel reverse proxy restrictions. So you can access the panel from bridge networks: http://remnawave:3000
        'x-forwarded-proto': 'https', // use this headers to bypass the panel reverse proxy restrictions. So you can access the panel from bridge networks: http://remnawave:3000
        Authorization: `Bearer ${this.configService.get('REMNAWAVE_API_TOKEN')}`
      }
    })

    const caddyAuthApiToken = this.configService.get('CADDY_AUTH_API_TOKEN')

    if (caddyAuthApiToken) {
      this.axiosInstance.defaults.headers.common['X-Api-Key'] = caddyAuthApiToken
    }
  }

  public async getUserByUsername(
    username: string
  ): Promise<ICommandResponse<GetUserByUsernameCommand.Response>> {
    try {
      const response = await this.axiosInstance.request<GetUserByUsernameCommand.Response>({
        method: GetUserByUsernameCommand.endpointDetails.REQUEST_METHOD,
        url: GetUserByUsernameCommand.url(username)
      })

      return {
        isOk: true,
        response: response.data
      }
    } catch (error) {
      if (error instanceof AxiosError) {
        this.logger.error('Error in Axios GetUserByUsername Request:', error.message)

        return {
          isOk: false
        }
      } else {
        this.logger.error('Error in GetUserByUsername Request:', error)

        return {
          isOk: false
        }
      }
    }
  }
}

Full examples

You can find full examples in the Remnawave Frontend repository and in the Remnawave Subscription page repository.