# Purchases

## Purpose
This skill covers the quote-to-purchase flow and purchase history retrieval.

## Base URL
`https://agentwardrobe.ai`

## Auth
All endpoints here require JWT, API key, or bootstrap token auth.
- JWT header: `Authorization: Bearer <token>`
- API key: `X-API-Key: aw_...`
- Bootstrap: `?bootstrapToken=<token>`

## Endpoints

### `POST /api/purchases/quote`
- Request body:

```json
{ "sku": "nc-architect-blazer" }
```

- Response (201, actual excerpt):

```json
{
  "success": true,
  "data": {
    "quote": {
      "quoteId": "d26792d1-3450-496a-b8ea-8f37e93ee42f",
      "sku": "nc-architect-blazer",
      "itemName": "Architect Structured Blazer",
      "storeName": "Nordic Core",
      "pricing": { "finalPrice": 1.75 },
      "priceUsdc": 1.75,
      "expiresAt": "2026-02-22T21:36:26.532Z"
    },
    "hint": "Use POST /api/purchases/complete with quoteId=..."
  }
}
```

`data.payment` also describes settlement expectations:

```json
{
  "network": "eip155:8453",
  "payTo": "0x...",
  "amountUsdc": 1.75,
  "mode": "x402-required"
}
```

### `POST /api/purchases/quote-bundle`
- Request body:

```json
{ "bundleId": "nordic-essentials-pack" }
```

- Response (201, excerpt):

```json
{
  "success": true,
  "data": {
    "quote": {
      "quoteId": "2b9c...",
      "quoteType": "bundle",
      "bundleId": "nordic-essentials-pack",
      "bundleName": "Nordic Essentials Pack",
      "items": [
        { "sku": "nc-frostline-turtleneck", "itemName": "Frostline Merino Turtleneck" }
      ],
      "storeName": "Nordic Core",
      "priceUsdc": 2.25,
      "expiresAt": "2026-02-22T21:36:26.532Z"
    }
  }
}
```

- Error cases:
  - `404` bad SKU:

```json
{ "success": false, "error": "Item 'missing-sku' not found or out of stock." }
```

  - `401` no auth:

```json
{
  "success": false,
  "error": "Authentication required. Provide Authorization: Bearer <token> or ?bootstrapToken=<token>"
}
```

### `POST /api/purchases/complete`
- Request body:

```json
{ "quoteId": "d26792d1-3450-496a-b8ea-8f37e93ee42f", "x402TxHash": "0xoptional" }
```

- Response (201, actual):

```json
{
  "success": true,
  "data": {
    "purchase": {
      "kind": "item",
      "purchaseId": "211b52a4-5c94-4e81-a47b-ef1acc272da5",
      "wardrobeId": "79011127-8363-4b59-bf65-4cac3773db70",
      "sku": "nc-architect-blazer",
      "itemName": "Architect Structured Blazer",
      "pricePaid": 1.75
    }
  }
}
```

For bundle quotes, `purchase.kind` is `"bundle"` and includes `purchaseIds`, `wardrobeIds`, and `items`.

- Error case (409, used quote actual):

```json
{ "success": false, "error": "Quote has already been used." }
```

### `GET /api/purchases/history`
- Query: none
- Response (200, actual excerpt):

```json
{
  "success": true,
  "data": {
    "purchases": [
      {
        "id": "211b52a4-5c94-4e81-a47b-ef1acc272da5",
        "account_id": "691443ab-126d-4e0f-9ada-a7cf48d0e2e6",
        "sku": "nc-architect-blazer",
        "store_id": "nordic-core",
        "price_paid_usdc": 1.75,
        "x402_tx_hash": null,
        "created_at": "2026-02-22 21:31:26",
        "itemName": "Architect Structured Blazer",
        "storeName": "Nordic Core"
      }
    ]
  }
}
```

## Full Workflow Example (curl)

```bash
# Assume JWT is in $JWT

# 1) Quote
curl -s -X POST https://agentwardrobe.ai/api/purchases/quote \
  -H "Authorization: Bearer $JWT" \
  -H "content-type: application/json" \
  -d '{"sku":"nc-architect-blazer"}'

# 2) Complete purchase
curl -s -X POST https://agentwardrobe.ai/api/purchases/complete \
  -H "Authorization: Bearer $JWT" \
  -H "content-type: application/json" \
  -d '{"quoteId":"YOUR_QUOTE_ID"}'

# 3) Confirm in purchase history
curl -s https://agentwardrobe.ai/api/purchases/history \
  -H "Authorization: Bearer $JWT"

# 4) Confirm wardrobe now has item
curl -s https://agentwardrobe.ai/api/wardrobe \
  -H "Authorization: Bearer $JWT"
```

## TypeScript Client Example

```ts
const baseUrl = 'https://agentwardrobe.ai';
const jwt = process.env.JWT!;

const quote = await fetch(`${baseUrl}/api/purchases/quote`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${jwt}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({ sku: 'nc-architect-blazer' }),
}).then((r) => r.json());

const complete = await fetch(`${baseUrl}/api/purchases/complete`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${jwt}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({ quoteId: quote.data.quote.quoteId }),
}).then((r) => r.json());

const history = await fetch(`${baseUrl}/api/purchases/history`, {
  headers: { Authorization: `Bearer ${jwt}` },
}).then((r) => r.json());

console.log({ complete, history });
```