@4players/fleet

@4players/fleet

Official TypeScript SDK for ODIN Fleet — Deploy and manage game servers globally.

Features

• Universal — Works in Browser, Node.js, Deno, Bun, and Edge Workers
• Tiny — ~28kb minified, only one runtime dependency (openapi-fetch)
• Type-safe — Full TypeScript support with OpenAPI-generated types
• Modern — ESM and CommonJS dual exports

Installation

npm install @4players/fleet

yarn add @4players/fleet

pnpm add @4players/fleet

Quick Start

import { FleetClient } from '@4players/fleet';

// Create client with your API token
const client = new FleetClient({
  apiToken: 'your-api-token-from-console.4players.io'
});

// Select an app to work with
client.selectApp(123456);

// List all servers
const servers = await client.getServers();
console.log(servers);

// Create a new deployment
const deployment = await client.createDeployment({
  name: 'EU Production',
  serverConfigId: 789,
  numInstances: 3,
  placement: {
    constraints: {
      country: 'de',
      city: 'frankfurt',
      cityDisplay: '',
      continent: '',
      isProtected: false
    }
  }
});

Usage Examples

Browser (React, Vue, Angular)

import { FleetClient } from '@4players/fleet';

// Client works directly in browsers with native fetch
const client = new FleetClient({ apiToken: userToken });

// List available locations
const locations = await client.getLocations();

Node.js

import { FleetClient } from '@4players/fleet';

const client = new FleetClient({
  apiToken: process.env.FLEET_API_TOKEN!
});

client.selectApp(Number(process.env.FLEET_APP_ID));

// Start all servers
await client.startAllServersForApp();

Deno

import { FleetClient } from 'npm:@4players/fleet';

const client = new FleetClient({
  apiToken: Deno.env.get('FLEET_API_TOKEN')!
});

API Overview

Apps

// List all apps
const apps = await client.getApps();

// Create a new app
const app = await client.createApp({ name: 'My Game' });

// Select an app for subsequent operations
client.selectApp(app.data.id);

Images (Binaries)

// List all images
const images = await client.getImages();

// Create a Docker image reference
const image = await client.createImage({
  name: 'GameServer',
  version: '1.0.0',
  type: 'dockerImage',
  os: 'linux',
  dockerImage: {
    imageName: 'ghcr.io/myorg/gameserver:1.0.0',
    registryId: 123
  }
});

Server Configs

// List all configs
const configs = await client.getConfigs();

// Create a new config
const config = await client.createConfig({
  name: 'Production',
  binaryId: image.data.id,
  resourcePackageSlug: 'standard',
  ports: [
    { name: 'Game Port', targetPort: 7777, protocols: ['udp'] }
  ],
  env: [
    { key: 'SERVER_NAME', value: 'Production', type: 'static' }
  ],
  mounts: [],
  restartPolicy: { condition: 'any' }
});

Deployments

// List all deployments
const deployments = await client.getDeployments();

// Create a deployment (starts servers)
const deployment = await client.createDeployment({
  name: 'EU Production',
  serverConfigId: config.data.id,
  numInstances: 3,
  placement: {
    constraints: {
      country: 'de',
      city: 'frankfurt',
      cityDisplay: '',
      continent: '',
      isProtected: false
    }
  }
});

// Scale deployment
await client.updateDeployment(deployment.data.id, {
  name: 'EU Production',
  numInstances: 5
});

// Delete deployment (stops all servers)
await client.deleteDeployment(deployment.data.id);

Servers

// List all running servers
const servers = await client.getServers();

// Get server details
const server = await client.getServer(serverId);

// Server lifecycle
await client.startServer(serverId);
await client.stopServer(serverId);
await client.restartServer(serverId);

// Get server logs
const logs = await client.getServerLogs(serverId, {
  tail: 100,
  timestamps: true
});

Server Metadata (Matchmaking)

// Update server metadata for matchmaking
await client.updateServerMetadata(serverId, {
  instance_state: 'occupied',
  game_mode: 'deathmatch',
  player_count: 8,
  max_players: 16,
  map_name: 'de_dust2'
});

// Mark server as available
await client.updateServerMetadata(serverId, {
  instance_state: 'idle',
  player_count: 0
});

Backups

// Create a backup
await client.createBackup(serverId, { name: 'Pre-update backup' });

// Restore from backup
await client.restoreBackup(serverId);

// Get download URL
const { data } = await client.getBackupDownloadUrl(serverId);

Bulk Operations

// Start/stop all servers for an app
await client.startAllServersForApp();
await client.stopAllServersForApp();

// Start/stop servers for a specific deployment
await client.startServersForDeployment(deploymentId);
await client.stopServersForDeployment(deploymentId);

Error Handling

The SDK provides typed error classes for different failure scenarios:

import {
  FleetClient,
  FleetError,
  FleetAuthError,
  FleetNotFoundError,
  FleetNoAppSelectedError
} from '@4players/fleet';

try {
  const servers = await client.getServers();
} catch (error) {
  if (error instanceof FleetAuthError) {
    console.error('Invalid API token');
  } else if (error instanceof FleetNoAppSelectedError) {
    console.error('Please select an app first');
  } else if (error instanceof FleetNotFoundError) {
    console.error('Resource not found');
  } else if (error instanceof FleetError) {
    console.error('Fleet API error:', error.message, error.statusCode);
  }
}

TypeScript Support

All request and response types are available:

import type {
  App,
  Server,
  ServerConfig,
  Binary,
  AppLocationSetting,
  Location,
  // Request types
  StoreServerConfigRequest,
  StoreAppLocationSettingRequest,
  // Full OpenAPI types for advanced usage
  paths,
  components,
  operations
} from '@4players/fleet';

Configuration

const client = new FleetClient({
  // Required: API token from console.4players.io
  apiToken: 'your-api-token',

  // Optional: Custom base URL (default: https://fleet.4players.io/api)
  baseUrl: 'https://custom-fleet-url.com/api',

  // Optional: Custom fetch implementation
  fetch: customFetch
});

Resources

• Dashboard: console.4players.io
• Documentation: docs.4players.io/fleet
• API Reference: fleet.4players.io/docs/api
• Discord: 4np.de/discord

License

MIT © 4Players GmbH