@mirasaki/a2s-server-probe

Type-safe TypeScript client, schemas, and route definitions for the A2S Server Probe API.

Query Steam game-servers using the A2S protocol with full type safety and zero-runtime overhead.

Note: The a2s-server-probe API is a proprietary service currently provided for free (subject to rate limits) without authentication. Terms and pricing may change. For production use, please contact us to discuss long-term API availability.

Features

• 🎯 Type-safe API contracts – Full TypeScript support with Zod schemas
• 📦 Modular exports – Import only what you need: routes, schemas, client, or types
• 🚀 Framework agnostic – Works with any HTTP client
• 📋 Runtime validation – Zod schemas validate responses
• 🔌 Dual ESM/CJS – CommonJS and ES Modules support
• 💾 Minimal footprint – Tree-shakeable exports

Installation

npm install @mirasaki/a2s-server-probe
pnpm add @mirasaki/a2s-server-probe
yarn add @mirasaki/a2s-server-probe

Quick Start

Using the pre-built client

import { createClient } from "@mirasaki/a2s-server-probe";

const client = createClient({
	baseUrl: "https://a2s-server-probe.mdgn.cloud",
});

const response = await client.request("/health/:ip/:port", {
	method: "GET",
  params: {
		ip: "109.230.227.167",
		port: "27023",
  }
});

if (!response.ok) {
	console.error(`Error: ${response.statusCode} - ${response.message}`);
  return;
}

const { data } = response;

if ('error' in data) {
  console.error(`Error: ${data.error}`);
  return;
}

if (data.status === 'offline') {
  console.log(`Server offline: ${data.info.error}`);
  return;
}

console.log(`Server online: ${data.info.name}`);
console.log(
  `Players: ${data.info.players}/${data.info.max_players}`
);

Using schemas directly

import { HealthResponseSchema, OnlineResponseSchema } from "@mirasaki/a2s-server-probe/schemas";

const result = HealthResponseSchema.parse(storageData);

if (result.status === "online") {
  console.log(result.info.name);
}

Using route definitions

import { routes } from "@mirasaki/a2s-server-probe/routes";

// Access route metadata
const healthRoute = routes["/health/:ip/:port"];
const pingRoute = routes["/ping"];

// Use with your own HTTP client library

Exports

/client

Pre-configured API client using @md-oss/api-types.

import { createClient, type Client } from "@mirasaki/a2s-server-probe/client";

/routes

Route registry with endpoint definitions.

import { routes, type Routes } from "@mirasaki/a2s-server-probe/routes";

/schemas

Zod schemas for all API requests and responses.

import {
  ServerInfoSchema,
  HealthPathParametersSchema,
  HealthResponseSchema,
  // ...
} from "@mirasaki/a2s-server-probe/schemas";

/types

TypeScript type definitions inferred from schemas.

import type {
  ServerInfo,
  HealthPathParameters,
  HealthResponse,
  // ...
} from "@mirasaki/a2s-server-probe/types";

API Overview

GET /ping

Liveness probe – always returns 200 {"status": "ok"}.

const response = await client.GET("/ping");
// { status: "ok" }

GET /health/:ip/:port

Query a Steam game-server via A2S protocol.

Parameters:

• ip (string) – IPv4, IPv6, or hostname of the game-server
• port (string) – Query port of the game-server (1-65535)

Responses:

Online (200):

{
  status: "online",
  server: "109.230.227.167:27023",
  response_time_ms: 42.5,
  info: {
    name: "My DayZ Server",
    map: "chernarusplus",
    game: "DayZ",
    players: 40,
    max_players: 60,
    bots: 0,
    version: "1.25.157458",
    ping: 18.3
  }
}

Offline (503):

{
  status: "offline",
  server: "109.230.227.167:27023",
  info: {
    error: "timed out"
  }
}

Error (400):

{
  error: "Invalid host: 'invalid-ip'"
}

Complete Example

import { createClient, HealthResponseSchema } from "@mirasaki/a2s-server-probe";

const client = createClient({
  baseUrl: "https://a2s-server-probe.mdgn.cloud",
});

async function checkServer(ip: string, port: string) {
  try {
    const response = await client.GET("/health/:ip/:port", {
      params: { ip, port },
    });

    if (!response.ok) {
      throw response;
    }

    const { data } = response;

    if (data.status === "online") {
      console.log(`✅ ${data.info.name}`);
      console.log(`   Players: ${data.info.players}/${data.info.max_players}`);
      console.log(`   Response time: ${data.response_time_ms}ms`);
    } else if (data.status === "offline") {
      console.log(`❌ Server offline: ${data.info.error}`);
    }
  } catch (error) {
    console.error("Request failed:", error);
  }
}

checkServer("109.230.227.167", "27023");

License

ISC

Support

• 🐛 Report issues
• 📖 View source
• 💬 Discussions