SKILL.md - market-sales-tracker

# SKILL.md - market-sales-tracker

## Overview

The market-sales-tracker skill records and queries direct-market farm sales data. It provides tools for creating sale events with line items, retrieving revenue summaries, and comparing performance across markets and products.

## Available Tools

### record_sale

Record a completed market day sale event with all line items.

**Input schema:**
```typescript
{
  market_id: string;        // UUID of the market
  date: string;             // ISO date: "2025-03-20"
  start_time?: string;      // "08:00"
  end_time?: string;        // "13:00"
  customer_count?: number;
  weather?: string;         // free text: "Sunny 72F"
  notes?: string;
  cash?: number;            // payment split
  card?: number;
  other?: number;
  line_items: Array<{
    product_id: string;     // UUID of the product
    quantity_sold: number;  // decimal allowed
    unit_price: number;     // dollars
  }>;
}
```

**Returns:**
```typescript
{
  event_id: string;
  total_revenue: number;
  line_item_count: number;
}
```

**Rules:**
- Inserts event header and all line items in a single atomic transaction
- Computes `line_total = quantity_sold * unit_price` per line item
- Computes `total_revenue = sum(line_totals)`
- If payment split is provided, validates `cash + card + other` equals `total_revenue` within $0.01

---

### get_revenue_summary

Get aggregated revenue for a time range, optionally filtered by market.

**Input schema:**
```typescript
{
  date_from: string;        // ISO date
  date_to: string;          // ISO date
  market_id?: string;       // optional filter
  group_by?: "day" | "week" | "month" | "season";  // default: "week"
}
```

**Returns:**
```typescript
{
  total_revenue: number;
  event_count: number;
  avg_per_event: number;
  best_event: { date: string; market: string; revenue: number } | null;
  periods: Array<{
    period_key: string;     // "2025-W12", "2025-03", "Spring 2025"
    revenue: number;
    event_count: number;
  }>;
}
```

---

### get_top_products

Get top products by revenue for a date range.

**Input schema:**
```typescript
{
  date_from: string;
  date_to: string;
  market_id?: string;       // optional filter
  limit?: number;           // default 10
}
```

**Returns:**
```typescript
{
  products: Array<{
    product_id: string;
    product_name: string;
    category: string;
    unit: string;
    total_revenue: number;
    total_quantity: number;
    avg_price: number;
    event_count: number;
  }>;
}
```

---

### get_market_summary

Get performance summary for a specific market.

**Input schema:**
```typescript
{
  market_id: string;
  date_from?: string;       // defaults to current season start
  date_to?: string;         // defaults to today
}
```

**Returns:**
```typescript
{
  market_id: string;
  market_name: string;
  market_type: string;
  total_revenue: number;
  event_count: number;
  avg_per_event: number;
  avg_customers: number | null;
  top_products: Array<{ product_name: string; revenue: number }>;
  recent_events: Array<{ date: string; revenue: number; customers: number | null }>;
}
```

---

### list_markets

List all markets with basic stats.

**Input schema:** `{}`

**Returns:**
```typescript
{
  markets: Array<{
    market_id: string;
    name: string;
    type: "farmers_market" | "farm_stand" | "csa" | "wholesale" | "restaurant" | "other";
    schedule: string | null;     // e.g. "Saturday 8am-1pm"
    revenue_ytd: number;
    event_count_ytd: number;
    last_event_date: string | null;
  }>;
}
```

---

### list_products

List all products with revenue data.

**Input schema:**
```typescript
{ category?: string }    // optional filter
```

**Returns:**
```typescript
{
  products: Array<{
    product_id: string;
    name: string;
    category: string;
    unit: string;
    default_price: number;
    revenue_ytd: number;
    qty_sold_ytd: number;
    avg_price_ytd: number;
  }>;
}
```

## Usage Notes

- All monetary values are in US dollars rounded to 2 decimal places
- Dates are ISO 8601: `YYYY-MM-DD`
- Season grouping reads from the `settings` table; falls back to `month` if not configured
- The `record_sale` tool requires all `product_id` and `market_id` values to exist in the database; unknown IDs return a 422 error with a `not_found` field indicating which ID failed
- Revenue computations are performed in SQL (not in JavaScript) for correctness on large datasets