{
  "openapi": "3.1.0",
  "info": {
    "title": "Livewell Travel API",
    "version": "0.1.0",
    "description": "REST API for Livewell Travel (艾旅) — private luxury cruise and travel advisory service. Submit consultation requests, check service health, and access agent capabilities.",
    "contact": {
      "name": "Livewell Travel 艾旅",
      "url": "https://livewelltravel.com",
      "email": "info@livewelltravel.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://livewelltravel.com/about"
    }
  },
  "servers": [
    {
      "url": "https://livewelltravel.com/api",
      "description": "Production API"
    }
  ],
  "tags": [
    {"name": "health", "description": "Service health and availability"},
    {"name": "consultation", "description": "Private consultation lead management"},
    {"name": "agent", "description": "AI agent discovery and capabilities"}
  ],
  "paths": {
    "/healthz": {
      "get": {
        "operationId": "healthCheck",
        "tags": ["health"],
        "summary": "Health check",
        "description": "Returns server health status. Use this to verify the service is live before making other calls.",
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/HealthStatus"},
                "example": {"status": "ok"}
              }
            }
          }
        }
      }
    },
    "/consultation": {
      "post": {
        "operationId": "submitConsultation",
        "tags": ["consultation"],
        "summary": "Submit consultation request",
        "description": "Submit a private travel consultation lead to Livewell Travel advisors. Returns a consultation record with ID for verification. The advisor will follow up within 24 hours.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/ConsultationInput"},
              "example": {
                "name": "Wang Wei",
                "email": "wang@example.com",
                "phone": "+886-912-345678",
                "preferredLanguage": "zh-TW",
                "travelType": "luxury-cruise",
                "destinationInterest": "Mediterranean",
                "preferredBrand": "Seabourn",
                "travelMonth": "2026-09",
                "numberOfTravelers": "2",
                "estimatedBudget": "USD 30,000+",
                "whatMattersMost": "service warmth and dining quality",
                "message": "First time on ultra-luxury cruise, want personal advisory",
                "consent": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Consultation lead saved. Returns record with ID.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/ConsultationLead"}
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/ApiError"}
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listConsultations",
        "tags": ["consultation"],
        "summary": "List consultation leads",
        "description": "Returns all consultation leads ordered by creation date (admin use).",
        "responses": {
          "200": {
            "description": "List of consultation leads",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {"$ref": "#/components/schemas/ConsultationLead"}
                }
              }
            }
          }
        }
      }
    },
    "/agent": {
      "get": {
        "operationId": "getAgentCapabilities",
        "tags": ["agent"],
        "summary": "Agent capabilities",
        "description": "Returns machine-readable agent capabilities including all endpoints, skills, and discovery links for AI agent integration.",
        "responses": {
          "200": {
            "description": "Agent capabilities object",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/AgentCapabilities"}
              }
            }
          }
        }
      }
    },
    "/indexnow/ping": {
      "post": {
        "operationId": "pingIndexNow",
        "tags": ["agent"],
        "summary": "Ping IndexNow",
        "description": "Submits site URLs to IndexNow (https://www.indexnow.org) for instant indexing notification to Bing and other participating search engines.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "urls": {
                    "type": "array",
                    "items": {"type": "string", "format": "uri"},
                    "description": "Optional list of URLs to submit. Defaults to all site URLs if omitted."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "IndexNow ping result",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/IndexNowResult"}
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "HealthStatus": {
        "type": "object",
        "properties": {
          "status": {"type": "string", "example": "ok"}
        },
        "required": ["status"]
      },
      "ApiError": {
        "type": "object",
        "properties": {
          "error": {"type": "string"}
        },
        "required": ["error"]
      },
      "ConsultationInput": {
        "type": "object",
        "required": ["name", "email", "travelType", "consent"],
        "properties": {
          "name": {"type": "string", "minLength": 1, "description": "Full name of traveler"},
          "email": {"type": "string", "format": "email"},
          "phone": {"type": ["string", "null"], "description": "Phone number including country code"},
          "preferredLanguage": {"type": ["string", "null"], "enum": ["zh-TW", "en", null], "description": "Preferred advisory language"},
          "travelType": {"type": "string", "description": "Type of travel interest: luxury-cruise, private-tour, family-trip, comparison, other"},
          "destinationInterest": {"type": ["string", "null"], "description": "Preferred destination or region"},
          "preferredBrand": {"type": ["string", "null"], "description": "Preferred cruise brand if known"},
          "travelMonth": {"type": ["string", "null"], "description": "Preferred travel month (YYYY-MM) or season"},
          "numberOfTravelers": {"type": ["string", "null"]},
          "estimatedBudget": {"type": ["string", "null"], "description": "Budget range (e.g. 'USD 20,000-30,000 per person')"},
          "whatMattersMost": {"type": ["string", "null"], "description": "Key priorities: service, dining, privacy, expedition, family, etc."},
          "message": {"type": ["string", "null"], "description": "Free-form message to the advisor"},
          "consent": {"type": "boolean", "description": "Must be true to submit — confirms consent to contact"}
        }
      },
      "ConsultationLead": {
        "type": "object",
        "required": ["id", "name", "email", "travelType", "consent", "createdAt"],
        "properties": {
          "id": {"type": "integer", "description": "Unique consultation ID — use for verification"},
          "name": {"type": "string"},
          "email": {"type": "string"},
          "phone": {"type": ["string", "null"]},
          "preferredLanguage": {"type": ["string", "null"]},
          "travelType": {"type": "string"},
          "destinationInterest": {"type": ["string", "null"]},
          "preferredBrand": {"type": ["string", "null"]},
          "travelMonth": {"type": ["string", "null"]},
          "numberOfTravelers": {"type": ["string", "null"]},
          "estimatedBudget": {"type": ["string", "null"]},
          "whatMattersMost": {"type": ["string", "null"]},
          "message": {"type": ["string", "null"]},
          "consent": {"type": "boolean"},
          "createdAt": {"type": "string", "format": "date-time"}
        }
      },
      "IndexNowResult": {
        "type": "object",
        "properties": {
          "success": {"type": "boolean"},
          "statusCode": {"type": "integer"},
          "urlsSubmitted": {"type": "integer"},
          "message": {"type": "string"}
        }
      },
      "AgentCapabilities": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "description": {"type": "string"},
          "url": {"type": "string"},
          "capabilities": {"type": "object"},
          "endpoints": {"type": "array", "items": {"type": "object"}},
          "skills": {"type": "array", "items": {"type": "object"}}
        }
      }
    }
  }
}