VSKI v0.3.0

Features

OpenAPI Specification Support

OpenAPI 3.0.3 Specification:
- Complete OpenAPI spec generation for all API endpoints
- Served via /openapi.json and /openapi.html
Interactive API Documentation:
- Embedded Redoc UI with index.html
- Beautiful, responsive API documentation with Try It Now functionality
- JWT Bearer authentication support documented
- Custom theme matching VSKI branding
API Endpoint:
- GET /openapi.json - Retrieve OpenAPI 3.0.3 specification
- Can be imported into API clients (Postman, Insomnia, etc.)
- Used for auto-generating SDKs and documentation

Enhanced Database Management

Database Creation API:
- POST /api/databases - Create new database files dynamically
- Supports custom descriptions for user databases
- Automatic registration in _databases table
- Proper error handling and validation
Database Listing Improvements:
- GET /api/databases - List all databases with metadata
- Proper NULL handling for descriptions
- Alphabetical sorting for better UX
- Detailed error logging with structured logs (slog)
Database Management Service:
- Physical database file creation in DATA_DIR
- Automatic cleanup on creation failure
- Integration with existing database provider
Reserved Database Protection:
- default and stats databases are protected from deletion
- Cannot create databases with reserved names
- Clear error messages for reserved name violations

Collection Creation Restrictions

Stats Database Protection:
- Prevent collection creation in stats database
- stats is reserved for system metrics and analytics
- Returns clear error message when attempting to create collections
Enhanced Validation:
- Collection creation service now validates database name
- Prevents accidental data in system databases

Build Process Improvements

Simplified Default Build:
- make build now produces production binary without UPX compression
- Faster build times for development iterations
- Smaller binary footprint for production deployments
New Build Targets:
- make build-release - Production build with UPX compression for smallest size
- make build-prod - Production build without compression
- Clear separation between development and release builds

Installation

Binary

Download binary for your platform:

# Linux (standalone with embedded UI)
wget https://vski.sh/x/platform/releases/download/v0.3.0/vski-standalone
chmod +x vski-standalone
./vski-standalone

# Linux (API-only)
wget https://vski.sh/x/platform/releases/download/v0.3.0/vski
chmod +x vski
./vski

Docker

Pull and run official Docker image:

# Light version (API only, no embedded UI)
docker pull vski.sh/x/vski:latest

# Standalone version (with embedded web UI)
docker pull vski.sh/x/vski:latest-standalone

# Pull specific version
docker pull vski.sh/x/vski:v0.3.0
docker pull vski.sh/x/vski:v0.3.0-standalone

# Run light version with default configuration
docker run -p 3000:3000 -v $(pwd)/data:/app/data vski.sh/x/vski:latest

# Run standalone version with embedded web UI
docker run -p 3000:3000 -v $(pwd)/data:/app/data vski.sh/x/vski:latest-standalone

Configuration

Create a .env file:

DATA_DIR=./data
SERVER_PORT=3000
JWT_SECRET=your-secret-key

Usage

Accessing OpenAPI Specification

# Get OpenAPI JSON spec
curl http://localhost:3000/openapi.json > openapi.json

# View interactive documentation
open http://localhost:3000/

Creating Databases via API

// Create a new database
const response = await fetch('http://localhost:3000/api/databases', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  },
  body: JSON.stringify({
    name: 'analytics',
    description: 'User analytics database'
  })
});

const database = await response.json();
console.log(database);
// { id: 'analytics', name: 'analytics', description: 'User analytics database' }

Listing Databases

// List all databases
const response = await fetch('http://localhost:3000/api/databases', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  }
});

const databases = await response.json();
console.log(databases);
// [
//   { id: 'default', name: 'default', description: 'Main database', created: '...', updated: '...' },
//   { id: 'stats', name: 'stats', description: 'Statistics database', created: '...', updated: '...' },
//   { id: 'analytics', name: 'analytics', description: 'User analytics database', created: '...', updated: '...' }
// ]

Error Handling

// Attempt to create reserved database name
try {
  const response = await fetch('http://localhost:3000/api/databases', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_JWT_TOKEN'
    },
    body: JSON.stringify({
      name: 'default'  // Reserved name!
    })
  });

  if (!response.ok) {
    const error = await response.json();
    console.error(error);
    // { error: 'Cannot create reserved database names (default, stats)' }
  }
} catch (error) {
  console.error('Failed to create database:', error);
}

// Attempt to create collection in stats database
try {
  const response = await fetch('http://localhost:3000/api/collections', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_JWT_TOKEN',
      'x-dbname': 'stats'  // Reserved database!
    },
    body: JSON.stringify({
      name: 'my_collection',
      schema: {}
    })
  });

  if (!response.ok) {
    const error = await response.json();
    console.error(error);
    // { error: 'cannot create collection in reserved database "stats"' }
  }
} catch (error) {
  console.error('Failed to create collection:', error);
}

Building from Source

# Clone repository
git clone https://vski.sh/x/platform.git
cd platform/vski

# Build production binary (no compression)
make build

# Build release binary (with UPX compression)
make build-release

# Run binary
./bin/vski

Migration Notes

Database Migration

No manual migration required. The _databases table is automatically initialized with default entries on server startup.

Breaking Changes

Database Creation Restrictions:

Cannot create databases named default or stats (reserved for system use)
Cannot create collections in stats database
These restrictions were previously unenforced but always intended

Build Process Changes:

make build no longer uses UPX compression by default
Use make build-release for compressed (smallest size) binaries
This change speeds up development builds while maintaining optimization for releases

Configuration Updates

No configuration changes required. All existing configurations work without modification.

API Endpoints

OpenAPI Specification

Method	Endpoint	Description
GET	`/openapi.json`	Retrieve OpenAPI 3.0.3 spec

Database Management

Method	Endpoint	Request Body	Description
GET	`/api/databases`	-	List all databases
POST	`/api/databases`	`{name, description?}`	Create new database
DELETE	`/api/databases/:name`	-	Delete database

Database Creation Response

{
  "id": "analytics",
  "name": "analytics",
  "description": "User analytics database"
}

Database List Response

[
  {
    "id": "default",
    "name": "default",
    "description": "Main database",
    "created": "2026-02-21T12:00:00Z",
    "updated": "2026-02-21T12:00:00Z"
  },
  {
    "id": "stats",
    "name": "stats",
    "description": "Statistics database",
    "created": "2026-02-21T12:00:00Z",
    "updated": "2026-02-21T12:00:00Z"
  }
]

Testing

Run E2E Tests

cd vski
make build
make e2e TEST=19_webhooks_test.ts  # Test webhook triggers
make e2e TEST=10_cron_test.ts       # Test cron integration

Test OpenAPI Spec

# Start server
./bin/vski

# Get and validate OpenAPI spec
curl http://localhost:3000/openapi.json | jq .

# Validate spec with OpenAPI validator
# (requires npx or global install)
npx @apidevtools/swagger-cli validate http://localhost:3000/openapi.json

Test Database Management

# Create database
curl -X POST http://localhost:3000/api/databases \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"name":"testdb","description":"Test database"}'

# List databases
curl http://localhost:3000/api/databases \
  -H "Authorization: Bearer YOUR_TOKEN"

# Try to create reserved database (should fail)
curl -X POST http://localhost:3000/api/databases \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"name":"default"}'

Documentation

Full documentation available at: https://vski.sh/x/platform

Interactive API documentation:

Local: http://localhost:3000/ (when running standalone binary)
OpenAPI Spec: http://localhost:3000/openapi.json

Changelog

v0.3.0 (2026-02-21)

Added

OpenAPI 3.0.3 specification generation for all API endpoints
/openapi.json endpoint for retrieving machine-readable API spec
Embedded Redoc UI (index.html) with interactive documentation
Database creation API (POST /api/databases)
Database listing with metadata and descriptions
Database deletion API with reserved name protection
Reserved database protection (default, stats from deletion)
Collection creation restriction in stats database
build-release make target for UPX-compressed production builds
logs/ directory to .gitignore

Changed

Default make build no longer applies UPX compression
Database list endpoint now sorts results alphabetically
Database creation now validates against reserved names
Collection creation service validates database name before creation
Database list now uses proper NULL handling for descriptions

Fixed

Database creation now creates physical database files
Database listing returns proper error messages on failure
Clear error messages for reserved database violations
Proper error logging with structured logs (slog)

Technical

Added github.com/getkin/kin-openapi v0.133.0 for OpenAPI spec generation
Updated related dependencies for OpenAPI support
Enhanced error handling throughout database management APIs
Improved documentation in AGENTS.md