HackArena 3.0 API Wrapper (TypeScript)

This project is a TypeScript-based API wrapper for the HackArena 3.0 hackathon game platform. It provides a convenient interface for interacting with the HackArena backend services, handling game state, race logic, and communication with the orchestrator and broker services.

Project Structure

├── LICENCE
├── package.json
├── README.md                # (this file)
├── TODO.md
├── tsconfig.json
├── src/                     # Main API wrapper source code
│   ├── cli.ts               # CLI entry point
│   ├── index.ts             # Library entry point
│   ├── Runner.ts            # Runner logic
│   ├── Runtime.ts           # Runtime management
│   ├── RuntimeDiscovery.ts  # Runtime discovery utilities
│   ├── types.ts             # Shared types and interfaces
│   └── internal/            # Internal modules
│       ├── api/             # API service clients
│       ├── auth/            # Authentication helpers
│       └── lib/             # Utilities (env, logger, etc.)
│   └── proto/               # Generated TypeScript from protobufs
├── template/
│   └── user/                # Template for user bots/projects
│       ├── package.json
│       ├── tsconfig.json
│       └── src/
├── third_party/             # External proto definitions
│   ├── HackArena-Proto/
│   └── HackArena3.0-Proto/
├── tools/                   # Utility scripts (e.g., proto generation)
│   └── generate-proto.js

Used Technologies

• TypeScript: Main language for type safety and modern JS features
• Node.js: Runtime environment
• gRPC / Protobuf: Communication with backend services

Available Scripts

Scripts are defined in package.json:

• npm install — Install dependencies
• npm run build — Compile TypeScript sources to JavaScript
• npm run dev — Start development mode (watch & run)
• npm run generate-proto — Generate TypeScript code from protobuf definitions (see tools/generate-proto.js)
• npm run bundle — Bundle and copy the files to the template project for distribution (tools/bundle.cjs)
• npm run release:{patch,minor,major} — Release a new version (tools/release.cjs {patch,minor,major})

Build & Release Flow

1. Install dependencies

   npm install

2. Generate protobufs (if proto files changed)

   npm run generate-proto

3. Build the project

   npm run build

4. Run in development mode

   npm run dev

5. Bundle the project (for distribution)

   npm run bundle

6. Release
   • Use one of the following scripts to bump the version and create a zip file of template project:
     • Patch release: npm run release:patch
     • Minor release: npm run release:minor
     • Major release: npm run release:major
   • Ensure all code is built and bundled.

Template User Project

The /template/user directory contains a starter template for user bots or projects. Copy or use this as a base for your own HackArena 3.0 bot implementations.