# Mobile API: Store Statistics Endpoint

## Overview

New endpoint providing comprehensive store statistics for the Store Details page. Combines real-time data with pre-aggregated historical metrics.

## Endpoint

```
POST /api/mobile
```

### Request

```json
{
  "APIKey": "your-api-key",
  "action": "storeStats",
  "store": "pc00"
}
```

### Response

```json
{
  "success": true,
  "storeId": "pc00",
  "date": "2025-12-02",

  "financials": {
    "sales": {
      "current": 4010.64,
      "goal": 2863.82,
      "percentOfGoal": 140.0,
      "status": "good"
    },
    "buys": {
      "current": 2021.93,
      "goal": 895.65,
      "percentOfGoal": 225.8,
      "outstanding": 2
    }
  },

  "today": {
    "buysCompleted": 12,
    "buysInQueue": 2,
    "containersProcessed": 16,
    "newCustomers": 6,
    "repeatCustomers": 6,
    "avgWaitMinutes": 13.3,
    "avgProcessMinutes": 7.2
  },

  "averages30Day": {
    "buysPerDay": 16.5,
    "containersPerDay": 29.2,
    "newCustomersPerDay": 12.0,
    "avgWaitMinutes": 38.4,
    "avgProcessMinutes": 7.9
  },

  "vsAverage": {
    "buys": {
      "value": -4.4,
      "formatted": "-27.1%",
      "status": "below"
    },
    "containers": {
      "value": -13.2,
      "formatted": "-45.2%",
      "status": "below"
    },
    "newCustomers": {
      "value": -6.0,
      "formatted": "-49.9%",
      "status": "below"
    }
  },

  "weekOverWeek": {
    "buysChange": "-19.3%",
    "salesChange": "-14.2%",
    "containersChange": "-8.3%",
    "thisWeekBuys": 176,
    "lastWeekBuys": 218
  },

  "customerSatisfaction": {
    "responseCount": 26,
    "npsScore": -56.5,
    "avgOverallRating": 4.58,
    "breakdown": {
      "greeting": 1.81,
      "waitTime": 1.69,
      "buyerKnowledge": 1.50,
      "overall": 4.58,
      "recommendation": 2.23
    }
  },

  "labor": {
    "enabled": true,
    "clockedInCount": 4,
    "totalHours": 14.7,
    "totalWages": 246.68,
    "laborPercent": "6%",
    "salesPerLaborHour": 272.79,
    "employees": [
      {
        "name": "Kay O.",
        "hours": 4.3,
        "wages": 71.28,
        "rate": 16.50
      }
    ]
  }
}
```

---

## Field Reference

### `financials`
Real-time sales and buys progress vs daily goals.

| Field | Type | Description |
|-------|------|-------------|
| `sales.current` | float | Today's sales total |
| `sales.goal` | float | Today's sales goal |
| `sales.percentOfGoal` | float | Progress percentage (current/goal * 100) |
| `sales.status` | string | `"good"` (≥100%), `"warning"` (≥90%), `"danger"` (<90%) |
| `buys.current` | float | Today's buy payouts total |
| `buys.goal` | float | Today's buys goal |
| `buys.percentOfGoal` | float | Progress percentage |
| `buys.outstanding` | int | Number of unpaid/pending buys |

---

### `today`
Real-time operations data for today.

| Field | Type | Description |
|-------|------|-------------|
| `buysCompleted` | int | Completed buys today |
| `buysInQueue` | int | Currently waiting in queue |
| `containersProcessed` | int | Total containers/bins processed today |
| `newCustomers` | int | First-time sellers today |
| `repeatCustomers` | int | Returning sellers today |
| `avgWaitMinutes` | float | Average wait time in minutes |
| `avgProcessMinutes` | float | Average processing time in minutes |

---

### `averages30Day`
Rolling 30-day averages (pre-computed daily at 5 AM).

| Field | Type | Description |
|-------|------|-------------|
| `buysPerDay` | float | Average buys per day |
| `containersPerDay` | float | Average containers per day |
| `newCustomersPerDay` | float | Average new customers per day |
| `avgWaitMinutes` | float | Average wait time in minutes |
| `avgProcessMinutes` | float | Average processing time in minutes |

---

### `vsAverage`
Comparison of today's numbers vs 30-day average.

| Field | Type | Description |
|-------|------|-------------|
| `*.value` | float | Numeric difference (today - average) |
| `*.formatted` | string | Formatted percentage with sign (e.g., `"+15.2%"`, `"-10.5%"`) |
| `*.status` | string | `"above"`, `"below"`, or `"equal"` (within ±5%) |

Available comparisons: `buys`, `containers`, `newCustomers`

---

### `weekOverWeek`
Comparison of last 7 days vs prior 7 days.

| Field | Type | Description |
|-------|------|-------------|
| `buysChange` | string | Percentage change with sign (e.g., `"+15.2%"`) |
| `salesChange` | string | Percentage change with sign |
| `containersChange` | string | Percentage change with sign |
| `thisWeekBuys` | int | Total buys in last 7 days |
| `lastWeekBuys` | int | Total buys in prior 7 days |

---

### `customerSatisfaction`
90-day rolling survey metrics.

| Field | Type | Description |
|-------|------|-------------|
| `responseCount` | int | Total survey responses in last 90 days |
| `npsScore` | float | Net Promoter Score (-100 to +100) |
| `avgOverallRating` | float | Average overall satisfaction (1-5 scale) |
| `breakdown.greeting` | float | Avg score for greeting quality |
| `breakdown.waitTime` | float | Avg score for wait time satisfaction |
| `breakdown.buyerKnowledge` | float | Avg score for buyer knowledge |
| `breakdown.overall` | float | Avg score for overall experience |
| `breakdown.recommendation` | float | Avg recommendation score (1-6, NPS-style) |

**NPS Calculation**: Based on `recommendation` score (step6):
- Promoters: 5-6
- Passives: 3-4
- Detractors: 1-2
- NPS = ((Promoters - Detractors) / Total) × 100

---

### `labor`
Labor data from WhenIWork integration (if enabled).

| Field | Type | Description |
|-------|------|-------------|
| `enabled` | bool | Whether WhenIWork is enabled for this store |
| `clockedInCount` | int | Number of employees currently clocked in |
| `totalHours` | float | Total labor hours today |
| `totalWages` | float | Total wages cost today |
| `laborPercent` | string | Labor as percentage of sales (e.g., `"6%"`) |
| `salesPerLaborHour` | float | Sales dollars per labor hour |
| `employees` | array | List of clocked-in employees |
| `employees[].name` | string | Employee name (format: "FirstName L.") |
| `employees[].hours` | float | Hours worked today |
| `employees[].wages` | float | Wages earned today |
| `employees[].rate` | float | Hourly rate |

**Note**: If `enabled` is `false`, only the `enabled` field is present.

---

## Status Values

### Goal Status (`financials.*.status`)
| Value | Meaning |
|-------|---------|
| `good` | At or above goal (≥100%) |
| `warning` | Close to goal (90-99%) |
| `danger` | Below goal (<90%) |
| `neutral` | No goal set |

### Comparison Status (`vsAverage.*.status`)
| Value | Meaning |
|-------|---------|
| `above` | More than 5% above average |
| `below` | More than 5% below average |
| `equal` | Within ±5% of average |

---

## UI Suggestions

### Financial Progress
Use `percentOfGoal` for progress bars, `status` for color coding (green/yellow/red).

### Today vs Average
Display `vsAverage.*.formatted` with color based on `status`:
- `above` → green (positive trend)
- `below` → red (needs attention)
- `equal` → neutral/gray

### Week-over-Week
Show arrows with `weekOverWeek.*Change` values. Parse the sign for direction.

### Customer Satisfaction
- Show `npsScore` as the headline metric
- NPS ranges: <0 = needs improvement, 0-30 = good, 30-70 = great, >70 = excellent
- Use `breakdown` for detailed drill-down

### Labor Section
Only show if `labor.enabled === true`. Display as a collapsible section showing who's working and current labor costs.

---

## Error Handling

If store not found or error occurs:
```json
{
  "success": false,
  "error": "Store not found"
}
```

If aggregate data not yet available (new store), `averages30Day` and `customerSatisfaction` will contain zeros/nulls - handle gracefully.