Trysail TypeScript SDK

Official TypeScript/JavaScript SDK for Trysail WireGuard Control Plane API.

Features

• 🚀 Full TypeScript support with type definitions
• 🎯 Promise-based async/await API
• 🔒 Type-safe API client
• 🌐 Works in Node.js and browser environments
• ⚡ Lightweight with minimal dependencies
• 🛡️ Built-in error handling
• 📦 Tree-shakeable ES modules

Installation

npm install @trysail/sdk
# or
yarn add @trysail/sdk
# or
pnpm add @trysail/sdk

Quick Start

import { TrysailClient } from '@trysail/sdk';

// Create client
const client = new TrysailClient({
  baseUrl: 'http://localhost:8081',
  timeout: 30000,
});

// List zones
const zones = await client.zones.list();

// Get specific zone
const zone = await client.zones.get('zone-id');

// Create zone
const newZone = await client.zones.create({
  name: 'my-zone',
  publicKey: 'public-key-here',
  endpoint: '192.168.1.1:51820',
  allowedIPs: ['10.0.0.0/24'],
});

// Update zone
await client.zones.update('zone-id', {
  status: 'inactive',
});

// Delete zone
await client.zones.delete('zone-id');

Configuration

import { TrysailClient, TrysailConfig } from '@trysail/sdk';

const config: TrysailConfig = {
  baseUrl: 'http://localhost:8081',
  timeout: 30000,
  headers: {
    'X-Custom-Header': 'value',
  },
};

const client = new TrysailClient(config);

API Reference

Client

TrysailClient

Main client class for interacting with the API.

const client = new TrysailClient(config: TrysailConfig);

Resources

Zones

// List all zones
const zones: Zone[] = await client.zones.list();

// Get zone by ID
const zone: Zone = await client.zones.get(zoneId: string);

// Create zone
const zone: Zone = await client.zones.create(data: CreateZoneRequest);

// Update zone
const zone: Zone = await client.zones.update(zoneId: string, data: UpdateZoneRequest);

// Delete zone
await client.zones.delete(zoneId: string): Promise<void>;

// Get zone configuration
const config = await client.zones.getConfiguration(zoneId: string);

Control Plane

// Get control plane status
const status = await client.controlPlane.getStatus();

// Sync zones from license server
const result = await client.controlPlane.syncZones();

// Get registered zones
const zones = await client.controlPlane.getRegisteredZones();

// Register a zone
const result = await client.controlPlane.registerZone(data);

// Get metrics
const metrics = await client.controlPlane.getMetrics();

Types

Zone

interface Zone {
  id: string;
  name: string;
  publicKey: string;
  endpoint?: string;
  allowedIPs: string[];
  persistentKeepalive?: string;
  status: 'active' | 'inactive';
  lastSeen?: string;
  metadata?: Record<string, any>;
}

CreateZoneRequest

interface CreateZoneRequest {
  name: string;
  publicKey: string;
  endpoint?: string;
  allowedIPs?: string[];
  persistentKeepalive?: string;
  metadata?: Record<string, any>;
}

UpdateZoneRequest

interface UpdateZoneRequest {
  name?: string;
  endpoint?: string;
  allowedIPs?: string[];
  status?: 'active' | 'inactive';
  metadata?: Record<string, any>;
}

Error Handling

import { TrysailError } from '@trysail/sdk';

try {
  const zone = await client.zones.get('zone-id');
} catch (error) {
  if (error instanceof TrysailError) {
    console.error('Status:', error.statusCode);
    console.error('Message:', error.message);
    console.error('Response:', error.response);
    
    // Check error type
    if (error.isNotFound()) {
      console.log('Zone not found');
    } else if (error.isUnauthorized()) {
      console.log('Unauthorized');
    } else if (error.isServerError()) {
      console.log('Server error');
    }
  }
}

Advanced Usage

Custom HTTP Client

import axios from 'axios';

const customAxios = axios.create({
  // Custom configuration
});

const client = new TrysailClient({
  baseUrl: 'http://localhost:8081',
  httpClient: customAxios,
});

Request Interceptors

import { TrysailClient } from '@trysail/sdk';

const client = new TrysailClient({
  baseUrl: 'http://localhost:8081',
});

// Add request interceptor
client.httpClient.interceptors.request.use((config) => {
  config.headers['Authorization'] = 'Bearer token';
  return config;
});

// Add response interceptor
client.httpClient.interceptors.response.use(
  (response) => response,
  (error) => {
    console.error('API Error:', error);
    return Promise.reject(error);
  }
);

Browser Usage

<!DOCTYPE html>
<html>
<head>
  <script type="module">
    import { TrysailClient } from 'https://cdn.jsdelivr.net/npm/@trysail/sdk/dist/index.mjs';
    
    const client = new TrysailClient({
      baseUrl: 'http://localhost:8081',
    });
    
    const zones = await client.zones.list();
    console.log(zones);
  </script>
</head>
<body>
</body>
</html>

Examples

See the examples directory for more usage examples:

• Basic Usage
• Error Handling
• Node.js Server
• React Integration

Development

# Install dependencies
npm install

# Build
npm run build

# Test
npm test

# Lint
npm run lint

# Type check
npm run type-check

Requirements

• Node.js >= 14.0.0
• TypeScript >= 4.5 (for development)

License

MIT

Support

For issues and questions, please visit GitHub Issues.