PLANS-BASED VALIDATION SDK

SDK Reference

The Aevs SDK runs validation plans against your sandboxes. Plans are declarative sequences of HTTP requests, wait conditions, and assertions — written once, executed on every PR.

Installation

TypeScript / Node

shell

npm install @aevs/sdk

C# / Unity / Unreal

shell

# NuGet
dotnet add package Aevs.SDK

# Unity Package Manager — add to Packages/manifest.json:
"com.aevs.sdk": "https://github.com/alxmss/aevs-unity-package.git"

Quick start

TypeScript

import { AevsClient } from '@aevs/sdk'

const client = new AevsClient({
  apiKey: process.env.AEVS_API_KEY,   // from /settings/api-keys
  projectId: process.env.AEVS_PROJECT_ID,
})

// createSandbox polls until status === 'active' (timeout: 120s)
const sandbox = await client.createSandbox({ branch: 'feat/matchmaking-v2' })

const result = await client.runPlan(sandbox.id, {
  id: 'matchmaking-smoke',
  steps: [
    { type: 'http', method: 'POST', path: '/v1/match/queue',
      body: { playerId: 'p1', mode: '4v4' } },

    { type: 'wait', condition: 'match.status === "active"', timeout: 10_000 },

    { type: 'http', method: 'GET', path: '/v1/match/active',
      assert: { players: { length: 8 } } },
  ],
})

if (!result.passed) {
  console.error('plan failed:', result.steps.filter(s => !s.passed))
  process.exit(1)
}

await client.teardownSandbox(sandbox.id)

Plan step types

type	fields	description
`http`	`method, path, body?, headers?, assert?`	Fire an HTTP request against the sandbox. Fails if status ≥ 400 or assert mismatches.
`wait`	`ms? \| condition + timeout?`	Sleep for ms milliseconds, or poll until condition evaluates truthy against the last response.
`assert`	`value, expected`	Evaluate a JSONPath expression against the last response body and compare to expected.
`websocket`	`path, send?, expect?, timeout?`	Open a WebSocket, optionally send a message, wait for an expected frame.

HTTP step — assert syntax

The assert field is a partial deep-equal against the response JSON body. Nested paths and array length checks are supported.

TypeScript

// Asserts res.body.players.length === 8
assert: { players: { length: 8 } }

// Asserts res.body.status === "active"
assert: { status: "active" }

// Asserts res.body.region === "eu-west-1" and res.body.latency < 50
assert: { region: "eu-west-1", latency: { $lt: 50 } }

C# example

using Aevs.SDK;

var client = new AevsClient(apiKey: Environment.GetEnvironmentVariable("AEVS_API_KEY"));
var sandbox = await client.CreateSandboxAsync(projectId, branch: "feat/lobby-v3");

var result = await client.RunPlanAsync(sandbox.Id, new Plan {
    Id = "lobby-smoke",
    Steps = new[] {
        new HttpStep { Method = "POST", Path = "/api/lobby/create",
                       Body = new { name = "test-lobby", maxPlayers = 4 } },
        new WaitStep { Condition = "lobby.state == \"open\"", TimeoutMs = 8000 },
        new HttpStep { Method = "GET", Path = "/api/lobby/test-lobby",
                       Assert = new { state = "open" } },
    }
});

Assert.IsTrue(result.Passed);
await client.TeardownSandboxAsync(sandbox.Id);

CI integration

Run your plan as a step in GitHub Actions. The GitHub App posts the result back as a commit status check — PRs are blocked until the plan passes.

yaml

# .github/workflows/aevs-validate.yml
name: aevs validation

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npx ts-node aevs.plan.ts
        env:
          AEVS_API_KEY: ${{ secrets.AEVS_API_KEY }}
          AEVS_PROJECT_ID: ${{ vars.AEVS_PROJECT_ID }}

Environment variables

variable	description
`AEVS_API_KEY`	API key from /settings/api-keys. Required.
`AEVS_PROJECT_ID`	Project UUID from /projects. Required for createSandbox.
`AEVS_API_URL`	Override API base URL. Defaults to https://aevs-api.fly.dev