# Catalog

## Purpose
This skill covers all public discovery endpoints: stores, catalog items, categories, bundles, and active sales.

## Inventory Rotation
Stores rotate their available inventory like a real retail clothing store:
- **Seasonal availability**: Each item has a `seasons` array (e.g. `["fall","winter"]`). Only items matching the current season appear in browse results and can be looked up by SKU.
- **Day-of-week availability**: Each item has a `days_of_week` array (e.g. `["monday","wednesday","friday"]`). Items only appear on their designated days.
- Items outside their rotation window are completely hidden — they won't appear in catalog listings, individual SKU lookups, category counts, or store item counts.
- **Owned items are unaffected** — once purchased, wardrobe items remain accessible regardless of rotation.
- Prices still vary by season (in-season, off-season, peak-season multipliers apply on top of rotation).

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

## Auth
No auth required.

## Endpoints

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

```json
{
  "success": true,
  "data": {
    "stores": [
      {
        "id": "nordic-core",
        "name": "Nordic Core",
        "itemCount": 10,
        "activeSales": [
          { "id": 1, "name": "Winter Clearance", "discount_percent": 20 },
          { "id": 2, "name": "Nordic Core Members Week", "discount_percent": 10 }
        ]
      }
    ]
  }
}
```

### `GET /api/stores/:storeId`
- Example path: `/api/stores/nordic-core`
- Response (200, actual excerpt):

```json
{
  "success": true,
  "data": {
    "store": {
      "id": "nordic-core",
      "name": "Nordic Core",
      "itemCount": 10,
      "bundles": [
        { "id": "nordic-essentials-pack", "bundle_price_usdc": 2.25 }
      ]
    }
  }
}
```

- Error (404, actual):

```json
{ "success": false, "error": "Store 'missing-store' not found." }
```

### `GET /api/catalog`
- Query options: `storeId`, `category`, `rarity`, `season`, `search`, `sortBy`, `sortDir`, `limit`, `offset`, `minPrice`, `maxPrice`
- Example: `/api/catalog?limit=3&sortBy=price&sortDir=desc`
- Response (200, actual excerpt):

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "sku": "nc-architect-blazer",
        "category": "outerwear",
        "rarity": "limited",
        "base_price_usdc": 1.46,
        "pricing": {
          "basePrice": 1.46,
          "storeMultiplier": 1,
          "seasonalMultiplier": 1,
          "rarityMultiplier": 1.5,
          "saleDiscount": 20,
          "finalPrice": 1.75
        },
        "storeName": "Nordic Core"
      }
    ],
    "total": 40,
    "limit": 3,
    "offset": 0,
    "hasMore": true
  }
}
```

### `GET /api/catalog/:sku`
- Example path: `/api/catalog/nc-architect-blazer`
- Response (200, actual excerpt):

```json
{
  "success": true,
  "data": {
    "item": {
      "sku": "nc-architect-blazer",
      "sub_category": "blazer",
      "pricing": { "finalPrice": 1.75 },
      "storeName": "Nordic Core"
    }
  }
}
```

- Error (404, actual):

```json
{ "success": false, "error": "Item 'invalid-sku' not found." }
```

### `GET /api/categories`
- Optional query: `storeId`
- Response (200, actual excerpt):

```json
{
  "success": true,
  "data": {
    "categories": [
      { "category": "outerwear", "count": 9 },
      { "category": "top", "count": 7 }
    ]
  }
}
```

### `GET /api/bundles`
- Optional query: `storeId`
- Response (200, actual excerpt):

```json
{
  "success": true,
  "data": {
    "bundles": [
      {
        "id": "nordic-essentials-pack",
        "store_id": "nordic-core",
        "bundle_price_usdc": 2.25,
        "individual_total_usdc": 2.44
      }
    ]
  }
}
```

### `GET /api/bundles/:bundleId`
- Example path: `/api/bundles/nordic-essentials-pack`
- Response (200, actual excerpt):

```json
{
  "success": true,
  "data": {
    "bundle": { "id": "nordic-essentials-pack", "store_id": "nordic-core" },
    "items": [
      { "sku": "nc-frostline-turtleneck", "name": "Frostline Merino Turtleneck" }
    ]
  }
}
```

- Error (404, actual):

```json
{ "success": false, "error": "Bundle 'invalid-bundle' not found." }
```

### `GET /api/sales`
- Optional query: `storeId`
- Response (200, actual excerpt):

```json
{
  "success": true,
  "data": {
    "sales": [
      { "id": 2, "name": "Nordic Core Members Week", "discount_percent": 10 },
      { "id": 1, "name": "Winter Clearance", "discount_percent": 20 }
    ]
  }
}
```

## Full Workflow Example (curl)

```bash
# List stores
curl -s https://agentwardrobe.ai/api/stores

# Inspect one store
curl -s https://agentwardrobe.ai/api/stores/nordic-core

# Browse catalog with filters
curl -s "https://agentwardrobe.ai/api/catalog?category=outerwear&rarity=limited&sortBy=price&sortDir=desc&limit=5"

# Get one SKU
curl -s https://agentwardrobe.ai/api/catalog/nc-architect-blazer

# Categories, bundles, sales
curl -s https://agentwardrobe.ai/api/categories
curl -s https://agentwardrobe.ai/api/bundles
curl -s https://agentwardrobe.ai/api/sales
```

## TypeScript Client Example

```ts
const baseUrl = 'https://agentwardrobe.ai';

const stores = await fetch(`${baseUrl}/api/stores`).then((r) => r.json());
const store = await fetch(`${baseUrl}/api/stores/nordic-core`).then((r) => r.json());
const catalog = await fetch(`${baseUrl}/api/catalog?search=blazer&limit=3`).then((r) => r.json());
const item = await fetch(`${baseUrl}/api/catalog/nc-architect-blazer`).then((r) => r.json());
const categories = await fetch(`${baseUrl}/api/categories`).then((r) => r.json());
const bundles = await fetch(`${baseUrl}/api/bundles`).then((r) => r.json());
const sales = await fetch(`${baseUrl}/api/sales?storeId=nordic-core`).then((r) => r.json());

console.log({ stores, store, catalog, item, categories, bundles, sales });
```