# KAIBEAUTY - Full Agentic Commerce Specifications

## Base URL
Production: `https://platform.kaibeauty.me` (or `https://kaibeauty.me`)

---

## 1. Product Search & Discovery
`GET /api/agent/products`

### Query Parameters
- `q` (string, optional): Keywords (e.g., "moisturizer", "niacinamide", "swanicoco")
- `skin_type` (string, optional): One of `dry`, `oily`, `combination`, `sensitive`, `normal`
- `concern` (string, optional): One of `hydration`, `barrier`, `soothing`, `tone`, `texture`, `elasticity`
- `avoid_ingredient` (string, optional): Ingredient to strictly avoid (e.g., "fragrance", "alcohol")
- `limit` (integer, default 10, max 30): Max items to return

### Sample Response
```json
{
  "total": 1,
  "products": [
    {
      "id": 29408,
      "variant_id": "gid://shopify/ProductVariant/4491823910123",
      "title": "Swanicoco Bio Growth Factor Peptide Eye Cream 20ml",
      "brand": "Swanicoco",
      "category": "SKIN",
      "price_usd": 15.42,
      "in_stock": true,
      "ingredients_inci": "Panax Ginseng Callus Culture Extract, Aspergillus/Rice Ferment Filtrate, Butylene Glycol, Stearic Acid, Glycerin, Niacinamide, ...",
      "matched_goals": ["hydration", "elasticity"],
      "caution_flags": []
    }
  ]
}
```

---

## 2. Transparent Cost Breakdown Quote
`POST /api/agent/quote`

Calculates itemized landed cost (product price, weight-based EMS shipping from Seoul, and estimated duties).

### Request Body
```json
{
  "items": [
    {
      "product_id": 29408,
      "quantity": 1
    }
  ],
  "country_code": "US",
  "postal_code": "90210"
}
```

### Response
```json
{
  "currency": "USD",
  "subtotal_usd": 15.42,
  "shipping_fee_usd": 4.50,
  "estimated_tax_duty_usd": 0.00,
  "total_landed_cost_usd": 19.92,
  "shipping_service": "Korea Post International Express EMS (4-7 business days)",
  "origin": "Seoul, South Korea",
  "all_items_in_stock": true
}
```

---

## 3. Delegated One-Click Checkout
`POST /api/agent/checkout`

Pre-creates a verified Shopify checkout cart and returns a direct payment URL for the user to approve.

### Request Body
```json
{
  "items": [
    {
      "product_id": 29848,
      "quantity": 1
    }
  ],
  "customer_email": "user@example.com"
}
```
*(Note: You can provide either `product_id` or `variant_id`)*

### Response
```json
{
  "checkout_url": "https://shop.kaibeauty.me/cart/c/Z2NwLXVzLWNlbnRyYWwxOjAx.../checkout",
  "cart_id": "gid://shopify/Cart/c1-...",
  "total_amount_usd": 19.92,
  "currency": "USD",
  "status": "ready_for_payment",
  "instructions_for_agent": "Present checkout_url to the user as a clickable link. Payment can be completed via Apple Pay, Google Pay, or Credit Card."
}
```