wg-easy-api

WireGuard API Client

Русский | English

Web-docs: Русский English

A robust Node.js client library for interacting with the WireGuard API, designed for WG-Easy servers.

Table of Contents

• About
• Features
• Installation
• Requirements
• Usage
• API Methods
• Response Format
• Debugging Tips
• Contributing
• License
• Changelog

About

This library provides a programmatic interface to the WireGuard API as implemented by WG-Easy.

Features

• Automatic session management with retries on 401 errors.
• Full coverage of WG-Easy API endpoints.
• Flexible authentication via password or cookies.
• Structured error handling.
• TypeScript support.

Installation

Install via npm:

npm install wg-easy-api

Requirements

• Node.js 12.x or higher.
• node-fetch (^2.7.0) - Included as a dependency.
• A running WG-Easy server (typically on port 51821).

Usage

Basic example with password:

const WireGuardAPI = require('wg-easy-api');

async function example() {
    const api = new WireGuardAPI('https', 'example.com', 51821, 'your-password');
    try {
        const auth = await api.initSession({ password: 'your-password' });
        const clients = await api.getClients();
        console.log('Clients:', JSON.stringify(clients, null, 2));
    } catch (error) {
        console.error('Error:', JSON.parse(error.message));
    }
}

example();

Using cookies:

const api = new WireGuardAPI('https', 'example.com', 51821, undefined, 'connect.sid=s%3A...');
const clients = await api.getClients();
console.log(clients);

Error handling:

try {
    const clients = await api.getClients();
} catch (error) {
    const err = JSON.parse(error.message);
    console.error(err.error, err.statusCode);
}

API Methods

All methods return a Promise resolving to { status, data|error, [statusCode], [details] }.

Session Management

• initSession({ password })
  Logs into the WG-Easy server with a password. Updates cookies automatically.

  • Params: { password: string } - WG-Easy password.
  • Returns: { status: 'success', data: any } or error (e.g., 401 for wrong password).
  • Example:
    await api.initSession({ password: 'myPass' }); // { status: 'success', data: { success: true } }

• getSession()
  Checks current session status.

  • Returns: { status: 'success', data: { authenticated: boolean } } or error.
  • Example:
    await api.getSession(); // { status: 'success', data: { authenticated: true } }

• createSession({ password })
  Creates a new session without auto-updating cookies.

  • Params: { password: string }.
  • Returns: Same as initSession.
  • Example:
    await api.createSession({ password: 'myPass' });

• deleteSession()
  Logs out by deleting the session.

  • Returns: { status: 'success', data: null } or error.
  • Example:
    await api.deleteSession(); // { status: 'success', data: null }

Client Operations

• getClients()
  Lists all WireGuard clients, converting timestamps to Date objects.

  • Returns: { status: 'success', data: Client[] } or error (e.g., 500 if server fails).
  • Example:
    await api.getClients(); // { status: 'success', data: [{ id: 'abc', name: 'Client1' }] }

• createClient({ name })
  Adds a new client with the given name.

  • Params: { name: string }.
  • Returns: { status: 'success', data: object } or error.
  • Example:
    await api.createClient({ name: 'MyLaptop' });

• deleteClient({ clientId })
  Removes a client by ID.

  • Params: { clientId: string }.
  • Returns: { status: 'success', data: null } or error.
  • Example:
    await api.deleteClient({ clientId: 'abc' });

• enableClient({ clientId })
  Enables a client to connect.

  • Params: { clientId: string }.
  • Returns: Same as above.
  • Example:
    await api.enableClient({ clientId: 'abc' });

• disableClient({ clientId })
  Disables a client.

  • Params: { clientId: string }.
  • Returns: Same as above.
  • Example:
    await api.disableClient({ clientId: 'abc' });

• updateClientName({ clientId, name })
  Changes a client’s name.

  • Params: { clientId: string, name: string }.
  • Returns: Same as above.
  • Example:
    await api.updateClientName({ clientId: 'abc', name: 'NewName' });

• updateClientAddress({ clientId, address })
  Updates a client’s IP address.

  • Params: { clientId: string, address: string }.
  • Returns: Same as above.
  • Example:
    await api.updateClientAddress({ clientId: 'abc', address: '10.0.0.3' });

Configuration and QR Code

• getClientConfig({ clientId })
  Gets a client’s .conf file as text.

  • Params: { clientId: string }.
  • Returns: { status: 'success', data: string } or error.
  • Example:
    await api.getClientConfig({ clientId: 'abc' }); // { status: 'success', data: '[Interface]...' }

• getClientQRCode({ clientId })
  Gets a client’s config as an SVG QR code.

  • Params: { clientId: string }.
  • Returns: { status: 'success', data: string } or error.
  • Example:
    await api.getClientQRCode({ clientId: 'abc' }); // { status: 'success', data: '...' }

• restoreConfiguration(file)
  Restores a server config from a string.

  • Params: file: string.
  • Returns: { status: 'success', data: null } or error.
  • Example:
    await api.restoreConfiguration('[Interface]...');

Miscellaneous

• getRelease()
  Gets the WG-Easy version.

  • Returns: { status: 'success', data: { version: string } } or error.
  • Example:
    await api.getRelease(); // { status: 'success', data: { version: '7' } }

• getLang()
  Gets the UI language.

  • Returns: { status: 'success', data: { lang: string } } or error.
  • Example:
    await api.getLang(); // { status: 'success', data: { lang: 'en' } }

• getUITrafficStats()
  Gets traffic stats.

  • Returns: { status: 'success', data: { bytesSent: number, bytesReceived: number } } or error.
  • Example:
    await api.getUITrafficStats(); // { status: 'success', data: { bytesSent: 12345 } }

• getChartType()
  Gets the UI chart type.

  • Returns: { status: 'success', data: { type: string } } or error.
  • Example:
    await api.getChartType(); // { status: 'success', data: { type: 'line' } }

Response Format

• Success: { status: 'success', data: any }
• Error: { status: 'error', error: string, statusCode: number, details: any }

Debugging Tips

• Check protocol, ip, port in constructor.
• Log api.cookies after initSession.
• Test with curl to verify server responses.

Contributing

Fork and PR on GitHub.

License

MIT © fluxnetru.