# Naveto Developer Guide & API Documentation

Technical documentation for integrating with the Naveto platform during the launch-waitlist stage.

## Platform Status & Availability

- **Current Stage:** Launch-waitlist stage.
- **Public Endpoints:** Public tRPC endpoints and OpenAPI specification require **no API key** (open unauthenticated access, rate-limited by IP).
- **Unavailable Features:** Hosted sandbox environments, live carpool ride search, seat reservation/booking, and payment rails are currently unavailable and deferred to post-launch.
- **User Consent Notice:** Automated agents must obtain explicit human user consent before submitting any contact details (email address or Moroccan mobile phone number) to the waitlist API.

## Canonical Resources

- **OpenAPI Specification:** [https://naveto.ma/openapi.json](https://naveto.ma/openapi.json)
- **Agent Guide (llms.txt):** [https://naveto.ma/llms.txt](https://naveto.ma/llms.txt)
- **Production API Worker Base URL:** `https://naveto-server-production-7227l4ptygid3bvi.orange-sound-4b9f.workers.dev`

## Available Endpoints

### 1. Health Check
Checks the operational readiness of the deployed Naveto API service.

- **Method & Route:** `GET /trpc/healthCheck`
- **Authentication:** None (No API key required)
- **Full URL:** `https://naveto-server-production-7227l4ptygid3bvi.orange-sound-4b9f.workers.dev/trpc/healthCheck`
- **Example cURL:**
  ```bash
  curl -s https://naveto-server-production-7227l4ptygid3bvi.orange-sound-4b9f.workers.dev/trpc/healthCheck
  ```
- **Response Format:**
  ```json
  {
    "result": {
      "data": "OK"
    }
  }
  ```

### 2. Join the Waitlist
Register a passenger or driver on the launch waitlist. Deduplicates existing contacts idempotently.

- **Method & Route:** `POST /trpc/waitlist.join`
- **Authentication:** None (No API key required)
- **Full URL:** `https://naveto-server-production-7227l4ptygid3bvi.orange-sound-4b9f.workers.dev/trpc/waitlist.join`
- **Content-Type:** `application/json`
- **Payload Schema:**
  - `contact` (string, required): Valid email address or Moroccan mobile phone number (+212 6... / +212 7... / 06... / 07...).
  - `contactType` (string, required): `"email"` | `"phone"`.
  - `role` (string, optional, default `"passenger"`): `"passenger"` | `"driver"`.
  - `source` (string, optional, default `"signup"`): `"signup"` | `"login"`.
- **Example cURL:**
  ```bash
  curl -X POST https://naveto-server-production-7227l4ptygid3bvi.orange-sound-4b9f.workers.dev/trpc/waitlist.join \
    -H "Content-Type: application/json" \
    -d '{"contact": "voyageur@example.com", "contactType": "email", "role": "passenger", "source": "signup"}'
  ```
- **Success Responses:**
  - Newly registered contact:
    ```json
    {
      "result": {
        "data": {
          "status": "created"
        }
      }
    }
    ```
  - Existing duplicate contact:
    ```json
    {
      "result": {
        "data": {
          "status": "duplicate"
        }
      }
    }
    ```

### 3. Error Responses
Structured JSON-RPC / tRPC error format:

```json
{
  "error": {
    "message": "Invalid contact: please provide a valid email address or Moroccan phone number.",
    "code": -32600,
    "data": {
      "code": "BAD_REQUEST",
      "httpStatus": 400,
      "path": "waitlist.join",
      "errorCode": "INVALID_CONTACT",
      "hint": "Provide a valid email address (e.g. name@example.com) or Moroccan phone number (+212 6... / 06...)."
    }
  }
}
```

## Localized Marketing Pages

- **French (Default):** [https://naveto.ma/fr](https://naveto.ma/fr) | [https://naveto.ma/index.md](https://naveto.ma/index.md)
- **English:** [https://naveto.ma/en](https://naveto.ma/en) | [https://naveto.ma/en.md](https://naveto.ma/en.md)
- **Arabic:** [https://naveto.ma/ar](https://naveto.ma/ar) | [https://naveto.ma/ar.md](https://naveto.ma/ar.md)