# `GET /api/health`
> **Endpoint:** `GET /api/health`  
> **Auth Scope:** Public Loopback (No secret required)  
> **Target Service:** Local DaemonX Bridge Daemon (`127.0.0.1:9123`)  
> **Introduced In:** v1.0.0  
> **Last Updated:** v1.0.0  

---

## 1. Description & Purpose

`GET /api/health` is an ultra-fast, unauthenticated liveness and readiness probe for the DaemonX Windows desktop bridge.

Web POS applications call this endpoint to verify:
1. Is the DaemonX background service running on the workstation?
2. Is the current counter paired and ready to print?

Wiring this endpoint into any frontend takes less than 5 minutes.

---

## 2. Request Contract

| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `Accept` | `string` | No | `application/json` |

### Query Parameters

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `counter_id` | `string` (UUID) | Optional | The specific counter profile to query. If omitted, DaemonX returns the currently active profile on the machine. |

---

## 3. TypeScript Contract

```typescript
export interface DaemonXHealthResponse {
  status: 'ok';
  online: boolean;
  app: string;
  version: string;
  port: number;
  counter_id: string | null;
  counter_name: string | null;
  counter_status: 'active' | 'not_paired' | 'disabled';
  is_paired: boolean;
  business_verified: boolean;
}
```

---

## 4. Response Field Matrix

| Field | Type | Description |
| :--- | :--- | :--- |
| `status` | `string` | Always `"ok"` if daemon is running. |
| `online` | `boolean` | `true` when the local DaemonX daemon handled the loopback request. This is a daemon liveness flag, not the Core heartbeat/offline allowance state. |
| `app` | `string` | Always `"DaemonX"`. |
| `version` | `string` | Installed desktop version (e.g. `"1.0.2"`). |
| `port` | `number` | Active HTTP port (defaults to `9123`). |
| `counter_id` | `string \| null` | UUID of the resolved counter profile. |
| `counter_name` | `string \| null` | Human-readable counter name (e.g. `"Counter 1"`). |
| `counter_status`| `string` | `"active"` when paired and usable, `"not_paired"`, or `"disabled"`. |
| `is_paired` | `boolean` | `true` if local workstation is paired and ready. |
| `business_verified` | `boolean` | `true` if the merchant's business entity is verified. |

---

## 5. Real-World Response Examples

### Example A: Paired Counter (200 OK)
```json
{
  "status": "ok",
  "online": true,
  "app": "DaemonX",
  "version": "1.0.2",
  "port": 9123,
  "counter_id": "d402ddec-ecf7-4b39-b57a-86ce6008df05",
  "counter_name": "Counter 1",
  "counter_status": "active",
  "is_paired": true,
  "business_verified": true
}
```

### Example B: Workstation Installed, Not Yet Paired (200 OK)
```json
{
  "status": "ok",
  "online": true,
  "app": "DaemonX",
  "version": "1.0.2",
  "port": 9123,
  "counter_id": null,
  "counter_name": null,
  "counter_status": "not_paired",
  "is_paired": false,
  "business_verified": false
}
```

---

## 6. Integration Snippets

### cURL
```bash
curl -X GET "http://127.0.0.1:9123/api/health" \
  -H "Accept: application/json"
```

### TypeScript Client Function
```typescript
export async function checkDaemonXHealth(
  counterId?: string
): Promise<DaemonXHealthResponse | null> {
  const url = counterId 
    ? `http://127.0.0.1:9123/api/health?counter_id=${encodeURIComponent(counterId)}`
    : 'http://127.0.0.1:9123/api/health';

  try {
    const res = await fetch(url, {
      method: 'GET',
      headers: { 'Accept': 'application/json' },
      signal: AbortSignal.timeout(2000), // 2s timeout
    });

    if (!res.ok) return null;
    return (await res.json()) as DaemonXHealthResponse;
  } catch {
    // DaemonX is not running on this host
    return null;
  }
}
```

### POS UI Indicator Example
```typescript
function getHardwareBridgeBadge(health: DaemonXHealthResponse | null) {
  if (!health) {
    return { status: 'DISCONNECTED', label: 'DaemonX Not Running', color: 'red' };
  }
  if (!health.is_paired) {
    return { status: 'UNPAIRED', label: 'Counter Not Paired', color: 'gray' };
  }
  return { status: 'READY', label: `Connected (${health.counter_name})`, color: 'emerald' };
}
```