# MilePrint - AI Agent Integration

> MilePrint (米乐印品) is a Chinese print-on-demand e-commerce platform specializing in custom notebooks, stationery, and packaging products.

## Agent API Base

Base URL: `https://api.mileyp.com/agent`

> **IMPORTANT**: The API base URL above points to the Medusa backend server, not the storefront website.
> Discovery files (this file, llms-full.txt) are hosted on the storefront, but all /agent/* API calls must be sent to the backend URL above.

## Quick Start for AI Agents

1. Browse products: `GET /agent/catalog`
2. Get product details + config schema: `GET /agent/catalog/{id}`
3. Validate configuration: `POST /agent/validate-configuration`
4. Get pricing: `POST /agent/calculate-price`
5. Create a proposal: `POST /agent/proposals`
6. Generate confirm link: `POST /agent/proposals/{id}/confirm-link`
7. Share confirm_url with the user to complete checkout

## Recommended Agent Behavior

Proposals are safe, editable drafts — not final orders.
They do NOT create carts, charge money, or deduct inventory.

1. **Understand the need**: Ask about purpose, quantity, preferences, budget
2. **Browse & suggest**: Use `GET /agent/catalog` to find products, present options
3. **Quote**: Use `POST /agent/calculate-price` to show pricing, let user review
4. **Create proposal when ready**: Once you have gathered sufficient information
   and the user has indicated their preferences (even approximately),
   go ahead and create the proposal. No need to ask "are you sure?" —
   proposals can be updated or regenerated at any time.
5. **Generate link**: `POST /agent/proposals/{id}/confirm-link`
6. **Share link**: Send confirm_url for user to finalize checkout

> KEY PRINCIPLE: Don't skip the requirements-gathering step,
> but also don't over-confirm. One round of clarification is usually enough.
> If the user has stated their needs clearly, proceed to create the proposal.

> NOTE: All API requests must use UTF-8 encoding.
> Set header: `Content-Type: application/json; charset=utf-8`
> When using PowerShell, ensure: `[Console]::OutputEncoding = [System.Text.Encoding]::UTF8`

## API Endpoints Overview

### Layer 1: Public Read-Only
- `GET /agent/catalog` — Browse published products with pagination
- `GET /agent/catalog/{id}` — Product details with customization schema
- `GET /agent/crafts` — Browse printing craft/technique information
- `GET /agent/crafts/{id}` — Craft detail (hot-stamping, lamination, etc.)
- `GET /agent/papers` — Browse paper types and specifications
- `GET /agent/formats` — Browse standard paper formats and dimensions
- `POST /agent/validate-configuration` — Validate product configuration
- `POST /agent/calculate-price` — Calculate price for a configuration

### Layer 2: Proposal Management
- `POST /agent/proposals` — Create a proposal draft
- `GET /agent/proposals/{id}` — View proposal details
- `PUT /agent/proposals/{id}` — Update proposal (draft status only)
- `POST /agent/proposals/{id}/confirm-link` — Lock proposal + generate confirmation link

### Layer 4: Partner Cart Management
- `POST /agent/cart` — Create Agent cart (requires x-agent-api-key)
- `POST /agent/cart/{id}/items` — Add items to cart (requires x-agent-api-key)
- `PUT /agent/cart/{id}/items/{itemId}` — Update cart item (requires x-agent-api-key)
- `DELETE /agent/cart/{id}/items/{itemId}` — Remove cart item (requires x-agent-api-key)
- `GET /agent/cart/{id}/summary` — Cart summary (read-only, no auth required)
- `POST /agent/cart/{id}/checkout-link` — Generate checkout link (requires x-agent-api-key)

## Common Query Parameters
- `lang=zh|en` — Language (default: zh)
- `limit=N` — Items per page (default: 20, max: 100)
- `offset=N` — Pagination offset
- `view=lite|summary|detail|full` — Response detail level

## Discovery Files
- `/llms.txt` — This file
- `/llms-full.txt` — Detailed API documentation with knowledge base summary
- `/.well-known/agent-info.json` — Machine-readable capability declaration
- `/agent/crafts-lite.json` — Lightweight craft index for quick filtering
- `/agent/papers-lite.json` — Lightweight paper index for quick filtering
- `/agent/formats-lite.json` — Lightweight format index for quick filtering

## Capabilities
- ✅ Product discovery and browsing
- ✅ Printing knowledge exploration (crafts, papers, formats)
- ✅ Customization schema for supported product categories
- ✅ Configuration validation
- ✅ Pricing calculation
- ✅ Proposal management (create, update, confirm)
- ✅ Partner cart management (with API key)
- ✅ Checkout confirmation page + login bridge