TypeScript SDK

The PiVirt TypeScript SDK provides a type-safe client for web applications, dashboards, and Node.js backend services to interact with PiVirt APIs via ConnectRPC.

Installation

npm install @pilab/pivirt
# or
yarn add @pilab/pivirt
# or
pnpm add @pilab/pivirt

Quick Start

import { VMServiceClient } from '@pilab/pivirt';

// Create client
const client = new VMServiceClient('https://agent.pilab.hu:8443', {
  tls: {
    ca: fs.readFileSync('ca.crt'),
    cert: fs.readFileSync('client.crt'),
    key: fs.readFileSync('client.key'),
  },
});

// List VMs
async function listVMs() {
  const vms = await client.listVMs({
    namespace: 'production',
  });

  for await (const vm of vms) {
    console.log(`VM: ${vm.name} (Status: ${vm.status})`);
  }
}

listVMs();

Authentication

mTLS

import { VMServiceClient } from '@pilab/pivirt';
import * as fs from 'fs';

const client = new VMServiceClient('https://agent.pilab.hu:8443', {
  tls: {
    ca: fs.readFileSync('ca.crt'),
    cert: fs.readFileSync('client.crt'),
    key: fs.readFileSync('client.key'),
  },
});

Bearer Token

const client = new VMServiceClient('https://agent.pilab.hu:8443', {
  metadata: {
    authorization: `Bearer ${token}`,
  },
});

VM Operations

Create VM

import { VMServiceClient, VMSpec, Disk, NetworkInterface } from '@pilab/pivirt';

const client = new VMServiceClient('https://agent.pilab.hu:8443');

const spec: VMSpec = {
  name: 'web-01',
  vcpus: 2,
  memoryBytes: BigInt(4294967296),
  disks: [
    {
      name: 'root',
      pool: 'default',
      sizeBytes: BigInt(21474836480),
      format: 'QCOW2',
      bus: 'virtio',
    } as Disk,
  ],
  nics: [
    {
      name: 'eth0',
      bridge: 'virbr0',
      model: 'virtio',
    } as NetworkInterface,
  ],
};

const vm = await client.createVM({
  spec,
  namespace: 'production',
});

console.log(`Created VM: ${vm.id}`);

Get VM

const vm = await client.getVM({
  id: 'vm-abc123',
  namespace: 'production',
});

console.log(`VM: ${vm.name}, Status: ${vm.status}`);

Start/Stop VM

// Start VM
await client.startVM({
  id: 'vm-abc123',
  namespace: 'production',
});

// Stop VM
await client.stopVM({
  id: 'vm-abc123',
  namespace: 'production',
});

Migrate VM

const operation = await client.migrateVM({
  id: 'vm-abc123',
  namespace: 'production',
  targetNode: 'node-02',
  options: {
    live: true,
    bandwidthLimitMbps: 1000,
    downtimeLimitMs: 500,
    compress: true,
  },
});

console.log(`Migration started: ${operation.id}`);

Storage Operations

Create Volume

import { StorageServiceClient } from '@pilab/pivirt';

const client = new StorageServiceClient('https://agent.pilab.hu:8443');

const volume = await client.createVolume({
  name: 'data-01',
  pool: 'default',
  sizeBytes: BigInt(107374182400),
  format: 'QCOW2',
});

console.log(`Created volume: ${volume.id}`);

Create Snapshot

const snapshot = await client.createSnapshot({
  volumeId: 'vol-abc123',
  name: 'backup-01',
});

console.log(`Created snapshot: ${snapshot.id}`);

Error Handling

import { PivirtError, ErrorCode } from '@pilab/pivirt';

try {
  const vm = await client.getVM({ id: 'vm-abc123' });
} catch (error) {
  if (error instanceof PivirtError) {
    switch (error.code) {
      case ErrorCode.NOT_FOUND:
        console.log('VM not found');
        break;
      case ErrorCode.PERMISSION_DENIED:
        console.log('Permission denied');
        break;
      case ErrorCode.UNAVAILABLE:
        console.log('Service unavailable');
        break;
      default:
        console.error(`Error: ${error.message}`);
    }
  }
}

TypeScript Types

import {
  VM,
  VMSpec,
  VMStatus,
  Disk,
  NetworkInterface,
  Volume,
  Snapshot,
  // ... more types
} from '@pilab/pivirt';

// Use types in your code
const vm: VM = {
  id: 'vm-abc123',
  name: 'web-01',
  status: VMStatus.RUNNING,
  // ...
};

Examples

See the examples directory for complete examples.