Analytics API

The analytics API provides tenant-scoped sales intelligence through three implemented reports and a magic-link share system for public report access.

Endpoints

POST /api/admin/analytics/:report/share

Generates a time-limited HMAC-signed share link for an analytics report.

Auth required: Admin session (cookie-based)

Path parameters:

• report — one of: revenue-overview, sales-velocity, product-performance

Request body:

{
  "period": "7d | 30d | 90d",
  "expiresInSeconds": 86400
}

period values:

Value	Window
7d	Last 7 days
30d	Last 30 days (default)
90d	Last 90 days

expiresInSeconds — optional; overrides the default TTL configured by ANALYTICS_SHARE_LINK_TTL_SECONDS (default 604800, 7 days). Must be a positive integer.

Response 201:

{
  "url": "https://app.example.com/api/reports/<token>",
  "expiresAt": "2026-05-02T00:00:00.000Z",
  "reportType": "revenue-overview",
  "period": {
    "from": "2026-03-25T00:00:00.000Z",
    "to": "2026-04-25T00:00:00.000Z"
  }
}

Error responses:

• 400 — unknown report type or invalid body
• 403 — missing admin session or tenant context
• 503 — ANALYTICS_SHARE_SIGNING_SECRET not configured

---

GET /api/reports/:token

Renders a public HTML report page. No authentication required; the token contains all required context.

Path parameters:

• token — HMAC-signed token from a share-link generation call

Response 200: text/html — interactive Chart.js report page

Error responses:

• 400 — missing token
• 403 — expired, tampered, or invalid token

---

GET /api/reports/:token/csv

Downloads a CSV export of the report. No authentication required.

Response 200: text/csv; charset=utf-8 — UTF-8 with BOM, RFC 4180

Headers on success:

• Content-Disposition: attachment; filename="<report-type>-<from>-<to>.csv"

Error responses:

• 400 — missing token
• 403 — expired, tampered, or invalid token
• 422 — CSV export not yet available for this report type (stubs)

---

Report types

Report type	Implemented	Discord command
revenue-overview	Yes	/report revenue [period]
sales-velocity	Yes	/report sales [period]
product-performance	Yes	/report products [period]
customer-insights	Stub	—
coupon-impact	Stub	—
time-of-day-heatmap	Stub	—
inventory-turnover	Stub	—
refund-cancel-rate	Stub	—
channel-performance	Stub	—
geographic-distribution	Stub	—

Stub reports return AnalyticsNotYetImplementedError when called. Full specification: docs/specs/2026-04-26-analytics.md.

---

Environment variables

Variable	Required	Description
ANALYTICS_SHARE_SIGNING_SECRET	Yes (for share links)	32-byte hex HMAC secret. Generate: openssl rand -hex 32
ANALYTICS_SHARE_LINK_TTL_SECONDS	No	Default link TTL. Default: 604800 (7 days). Min: 60.