# KosmoConnect Gateway Service

The **Gateway Service** handles all web-to-mesh and mesh-to-web messaging. It is the monetization boundary of the network.

## What It Does

- **Subscription Enforcement**: Validates that the user has an active subscription and that their plan allows messaging the target node
- **Quota Management**: Tracks monthly message usage and rejects requests when limits are exceeded
- **Outbound Queue**: Accepts web messages, stores them in PostgreSQL, and publishes them to MQTT for bridge delivery
- **Inbound Consumer**: Listens to `kosmo/mesh/inbound` and stores replies, automatically threading them into conversations
- **Delivery Tracking**: Message status progresses `pending -> queued -> transmitted -> delivered` (future: bridge ACKs will update to `transmitted`)

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/v1/messages` | Send a message to a mesh node |
| GET | `/api/v1/messages/conversations` | List all conversations for the user |
| GET | `/api/v1/messages/conversations/{node_id}` | Get full message history with a node |
| GET | `/api/v1/messages/{message_id}` | Check delivery status of a message |

## Authentication (v0.1)

For rapid development, the gateway currently uses a simple `X-User-ID` header to identify the caller. In production this will be replaced with JWT/OAuth2.

## Billing

Subscription management is handled by the [Billing Service](../billing/README.md), which integrates with the Church of Kosmo's BTCPay Server at `pay.cqre.net`. The Gateway does not process payments itself; it only reads subscription state from the shared PostgreSQL database.

## Subscription Scopes

| Plan | Scope | Quota (example) |
|------|-------|-----------------|
| `wanderer` | Any node on the mesh | 50/month |
| `guardian` | Only whitelisted nodes | 500/month |
| `sanctuary` | Any node + API/webhooks | Unlimited |
| `free` | Receive only | 0 outbound |

## Running Locally

Make sure the backend infrastructure (Postgres, MQTT) is running:

```bash
cd backend
docker-compose up -d
```

Seed test users (only needed once):

```bash
docker-compose exec -T timescaledb psql -U kosmo -d kosmoconnect < migrations/002_seed_test_users.sql
```

Start the gateway:

```bash
./run-dev.sh gateway
```

## Testing with cURL

```bash
# Send a message (test wanderer user)
curl -X POST http://localhost:8003/api/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-User-ID: 11111111-1111-1111-1111-111111111111" \
  -d '{"target_node_id": "!a1b2c3d4", "text": "Hello mesh"}'

# List conversations
curl http://localhost:8003/api/v1/messages/conversations \
  -H "X-User-ID: 11111111-1111-1111-1111-111111111111"

# Check message status
curl http://localhost:8003/api/v1/messages/{message_id} \
  -H "X-User-ID: 11111111-1111-1111-1111-111111111111"
```

## Architecture

```
Web Client
    |
    | POST /api/v1/messages  (X-User-ID)
    v
Gateway Service (:8003)
    |- Checks subscription + quota in PostgreSQL
    |- Writes message to mesh_messages (status=pending)
    |- Background worker publishes pending rows to MQTT
    |
    v
MQTT Broker  (kosmo/mesh/outbound/{node_id})
    |
    v
Bridge Daemon (Pi)  ->  Meshtastic Mesh  ->  Target Node

Reply path:
Target Node  ->  Mesh  ->  Bridge Daemon  ->  MQTT (kosmo/mesh/inbound)
    |
    v
Gateway Service consumes MQTT and writes reply to mesh_messages
    |
    v
Web Client reads via GET /api/v1/messages/conversations
```