typosaurus-sandbox/README.md

# retoor <retoor@molodetz.nl>

# typosaurus-sandbox

Sandbox for Typosaurus end-to-end verification.

A FastAPI application serving arithmetic operations over HTTP with JSON request/response bodies.

## Configuration

The application uses a single `.env.json` file at the project root as its central point of truth
for configuration. Defaults are plug-and-play and require no setup:

```json
{
    "host": "127.0.0.1",
    "port": 8000
}
```

When no `.env.json` is present, the application starts with these defaults. To customise, create
`.env.json` in the project root and populate only the keys that differ.

## Usage

### Start the server

```sh
python -m typosaurus_sandbox
```

The server listens on `http://127.0.0.1:8000` by default.

### Health check

```
GET /health
```

Response:

```json
{"status": "ok"}
```

## API endpoints

All calculator endpoints accept `POST` requests with a JSON body and return a JSON response.

### POST /api/v1/calculator/add

Add two integers.

Request:

```json
{"left": 3, "right": 5}
```

Response:

```json
{"result": 8}
```

### POST /api/v1/calculator/subtract

Subtract the right integer from the left.

Request:

```json
{"left": 10, "right": 3}
```

Response:

```json
{"result": 7}
```

### POST /api/v1/calculator/clamp

Clamp a value between a low and high bound.

Request:

```json
{"value": 15, "low": 0, "high": 10}
```

Response:

```json
{"result": 10}
```

Boundaries are inclusive. A `low > high` combination produces a 422 validation response.

### POST /api/v1/calculator/clamp-to-byte

Clamp an integer to the byte range [0, 255].

Request:

```json
{"value": 300}
```

Response:

```json
{"result": 255}
```

## Verification

```sh
make verify
```

Runs compile-all checks against all source and test files, then executes the full test suite.
Zero warnings are tolerated.