Reports & Analytics - API Reference

Audience: Frontend engineers (admin panel), backend engineers, QA, and API consumers. Scope: The 19 admin-only routes under /api/admin/analytics/ — dashboards, KPIs, trends, the report registry, exports, and the operator sync surface.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

5. Auth, Identity, and Permissions

• Ten permission modules: Analytics + ReportsSales · ReportsOrders · ReportsProducts · ReportsCustomers · ReportsPayments · ReportsPromotions · ReportsInventory · ReportsReviews · ReportsPos. _CREATE/_DELETE/_RESTORE unused (catalogue cross product).
• Rate limits per admin account (never per IP): reads ADMIN_ANALYTICS_READ 60/min; export submission ADMIN_ANALYTICS_EXPORT 5/hour; sync triggers ADMIN_HEAVY_OP 20/min.
• No id enumeration: an unpermitted report is the same 404 as a nonexistent one; another admin's export is the same 404 as a missing one.

6. DTO and Model Reference

6.1 AnalyticsPeriodQueryDto — every analytics/report/export request

6.2 AnalyticsRankedQueryDto — rankings

Extends the period DTO with limit (int ≥1, default 10) and, for top-products, sortBy (units/revenue).

6.3 ReportRunQueryDto — GET /reports/{reportId}

6.4 RequestReportExportDto — POST /exports

6.5 ListReportExportsDto — GET /exports

page (int ≥1, default 1), size (int 1–500, default 20).

6.6 AnalyticsSyncDto — the three trigger routes

RefreshSyncDto: { stream? } (string, optional — omit for all). BackfillSyncDto: { stream } (required). ReconcileSyncDto: { stream, windowDays? } (window default 30).

6.7 The meta envelope — on every data response

{
  "dataAsOf": "2026-08-07T10:42:10.000Z",
  "stalenessSeconds": 96,
  "behind": false,
  "period": { "preset": "this_month", "from": "2026-08-01", "to": "2026-08-07",
              "dayCount": 7, "timeZone": "Asia/Kathmandu" },
  "filters": { "channel": "pos" },
  "generatedAt": "2026-08-07T10:43:46.000Z",
  "durationMs": 41
}

KPIs add comparison: { ...previous window..., truncatedForFairness: true }. The dashboard summary replaces period with windows: { today, weekToDate, monthToDate }. Reports add report, sort, paging, and period: null for point-in-time reports.

7. Enum Reference

8. Endpoint Reference

8.1 GET /api/admin/analytics/dashboard

Purpose

The headline tiles: revenue/orders/customers/payments today, week-to-date and month-to-date, stock counts, pending moderation, average order value. Rollup-backed — three bounded reads over at most ~60 documents.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Analytics_READ · Rate limit: 60/min per admin

Request

Response

200 — data: revenue { today, weekToDate, monthToDate, todayVsYesterdayPercent? }, orders, customers, payments, inventory { lowStockCount, outOfStockCount }, reviews { awaitingModeration }, averageOrderValue. meta.windows names the three windows. todayVsYesterdayPercent is null when yesterday had no revenue.

Side Effects

None — reads daily rollups + product facts (stock counts).

Error Cases

8.2 GET /api/admin/analytics/kpis

Purpose

KPIs for an arbitrary period with a like-for-like comparison: netRevenue, grossRevenue, orders, completedOrders, cancelledOrders, unitsSold, newCustomers, averageOrderValue, failedPayments, checkoutConversionPercent (null when nothing started).

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Analytics_READ · Rate limit: 60/min

Request

Response

200 — each metric is { value, previous, changePercent } (changePercent null when previous was 0). meta.comparison.truncatedForFairness says the previous window was cut to the same elapsed length.

Side Effects

None.

Error Cases

8.3 GET /api/admin/analytics/trends

Purpose

Day-by-day series for charting: date, netRevenue, grossRevenue, orders, completedOrders, unitsSold, newCustomers — one row per dateKey.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Analytics_READ · Rate limit: 60/min

Side Effects

None. Freshness from the orders + customers streams.

8.4 GET /api/admin/analytics/funnel

Purpose

The conversion funnel: carts_created → checkouts_started → payment_started → payment_succeeded → orders_completed, with pairwise percentages, abandonedCheckouts, and unavailableStages naming product_viewed as unavailable (no view counter exists in PostgreSQL).

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Analytics_READ · Rate limit: 60/min

Side Effects

None. Cart counts are platform-wide and attributed to online — a cart has no channel until a checkout session is created from it.

8.5 GET /api/admin/analytics/channels

Purpose

Revenue and orders split by channel, so online and POS stay comparable without double counting — a counter sale is one order with channel: "pos", not a second record.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Analytics_READ · Rate limit: 60/min

8.6 GET /api/admin/analytics/payment-methods

Purpose

Payment-method distribution over the period ({ method, count }[]), from the rollup's map field.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Analytics_READ · Rate limit: 60/min

8.7 GET /api/admin/analytics/top-products

Purpose

Top products by units or revenue over the period. Reads order-line facts directly (not day-shaped), bounded by limit. Excludes cancelled orders.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Analytics_READ · Rate limit: 60/min

Request

8.8 GET /api/admin/analytics/geography

Purpose

Revenue, orders and customer count by district. Grouped by district id, never name — a province rename must not split history.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Analytics_READ · Rate limit: 60/min

8.9 GET /api/admin/analytics/reviews

Purpose

Rating distribution (1–5, zero-filled) over the period and the pending-moderation count.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Analytics_READ · Rate limit: 60/min

8.10 GET /api/admin/analytics/reports

Purpose

The report registry, filtered to what the caller may run — descriptors with id, title, description, category, permission, pointInTime, columns, filters, sortable, defaultSort. Build the report picker from this response; never hard-code the list.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Analytics_READ · Rate limit: 60/min

Response

200 — { items: [descriptor...] }, only reports whose Reports*_READ the caller holds.

Side Effects

None.

8.11 GET /api/admin/analytics/reports/{reportId}

Purpose

Run one registry report. Example:

GET /api/admin/analytics/reports/product_sales
      ?period=last_30_days
      &filters={"brandId":4,"channel":"pos"}
      &sortBy=revenue&sortDirection=desc
      &limit=50&offset=0

Filters travel as one URL-encoded JSON object — the global pipe runs forbidNonWhitelisted, and the filter set differs per report. An unsupported key is refused by name, never silently ignored.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Analytics_READ + the report's own · Rate limit: 60/min

Response

200 — data: { items, total, meta: { report, dataAsOf, stalenessSeconds, behind, period (null when pointInTime), filters, sort, paging, generatedAt, durationMs } }.

Error Cases

8.12 POST /api/admin/analytics/exports

Purpose

Queue a report export — asynchronous by design; a year of orders can aggregate for minutes. Returns immediately; poll GET /exports/{exportId} until ready, then follow downloadUrl.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Analytics_READ + the report's own · Rate limit: 5/hour per admin

Request

{
  "reportId": "sales_summary_by_day",
  "format": "xlsx",
  "period": "previous_month",
  "filters": "{\"channel\":\"pos\"}",
  "idempotencyKey": "sales-2026-07-a1b2c3"
}

Response

200 — { exportId, reportType, format, status: "queued", truncated: false, expiresAt, downloadUrl: null }.

Side Effects

Export record (Mongo) written FIRST, then analytics.build_export queued (job id = export id). Permission checked before anything is written.

Error Cases

Edge Cases

• Same idempotencyKey again → the existing export is returned, no second aggregation.
• Rate limit 5/hour — tighter than reads: each submission spawns an aggregation and writes a file.

8.13 GET /api/admin/analytics/exports

Purpose

The requesting admin's own exports, newest first, paginated.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Analytics_READ · Rate limit: 60/min

8.14 GET /api/admin/analytics/exports/{exportId}

Purpose

Poll one export. Scoped to its requester — another admin's export is the same 404 as a missing one.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Analytics_READ · Rate limit: 60/min

Response

200 — { exportId, reportType, format, status, requestedAt, startedAt?, completedAt?, rowCount?, truncated, fileSizeBytes?, expiresAt, error?, downloadUrl (only when ready) }. downloadUrl is the API route, never a storage key.

Error Cases

8.15 GET /api/admin/analytics/exports/{exportId}/download

Purpose

Download the finished file. Re-checks the report's permission against the caller's LIVE role — queueing an export before a role change must not preserve access.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Analytics_READ + the report's own (live) · Rate limit: 60/min

Error Cases

8.16 GET /api/admin/analytics/sync

Purpose

The operator freshness surface: every stream's state plus the pending-work backlog, with a rolled-up healthy. Three fields carry the diagnosis: consecutiveFailures (5 in a row = stopped pipeline), behind (page budget), driftCount (reconcile repairs).

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Analytics_READ · Rate limit: 60/min

Response

200 — { healthy, streams: [{ stream, status, parentDriven, watermarkAt, lastSuccessAt, lastDurationMs, lastDocumentsWritten, consecutiveFailures, behind, lastReconciledAt, driftCount, backfillCursor?, backfillCompletedAt?, lastError?, lockedUntil? }], pendingWork: { count, oldestAt } }. status: "parent_driven" on order_lines is normal.

8.17 POST /api/admin/analytics/sync/refresh

Purpose

Force the sync now — body { "stream": "orders" } or {} to sync everything in dependency order. Returns as soon as the job is queued; poll GET /sync and watch lastSuccessAt move.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Analytics_UPDATE · Rate limit: 20/min

Response

200 — { queued: true, stream: "orders" | null, correlationId }.

Error Cases

8.18 POST /api/admin/analytics/sync/backfill

Purpose

Rebuild a stream from the beginning. Resumable — each job walks a slice and records where it reached, so pressing it twice continues rather than restarts. Nothing is deleted — projections are idempotent upserts, so this rewrites documents in place. It is the repair for drift, not a destructive operation, but it is expensive — not something to run routinely.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Analytics_UPDATE · Rate limit: 20/min

Error Cases

8.19 POST /api/admin/analytics/sync/reconcile

Purpose

Re-project a historical window (default 30 days) ignoring the watermark, and report how much had to change via driftCount on GET /sync. Diagnostic: a healthy stream reports zero drift. Deliberately does not advance the watermark — a reconcile that made progress could mask an incremental path that is stuck.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Analytics_UPDATE · Rate limit: 20/min

Error Cases

9. Flow Diagrams

9.1 Route Ownership

9.2 Request Sequence (report run)

9.3 Error Branch (report run)

10. Pagination, Sorting, Filtering, and Search

Search filters (on reports that support them): prefix-anchored, case-insensitive, escaped — filters={"customerName":"ram"} matches "Ram Bahadur", not "Sita Ram". Substring search is not supported: the index cannot serve it, and an unanchored scan is exactly the expensive-query vector the rate limits bound.

11. Caching, Jobs, and External Integrations

13. Mandatory Deep API Documentation Pack

13.1 Route-by-Route Completeness Matrix

13.2 Request/Response Exhaustiveness

Covered in §6 and §8: the period DTO and every preset, the filters-as-JSON parameter with its forbidNonWhitelisted rationale, the export request with idempotency, the full meta envelope (§6.7), the report envelope with pointInTime behavior, per-endpoint error tables with the exact codes, and the 503-before-first-sync rule.

13.3 API Diagram Pack

Route ownership (§9.1), report-run sequence (§9.2), report-run error tree (§9.3), plus the export state machine and sync flow diagrams in the feature and backend docs.

13.4 Consumer Integration Notes

13.5 API Tradeoffs and Rationale

13.6 API Change Impact

14. Zero-Omission API Checklist

• Every controller route is documented (§4, §8, §13.1).
• Every parent route prefix and runtime URL is documented (§2, §4).
• Every DTO field, nested field, enum, default, transform, and validator is documented (§6, §7).
• Every response field, nullable field, generated field, and omitted raw entity field is documented (§6.7, §8).
• Every auth, guard, permission, role, and identity branch is documented (§5).
• Every success, validation, auth, permission, not-found, conflict, rate-limit, and server-error branch is documented (§8).
• Every database read/write, queue job, and external call is documented (§8 side effects, §11).
• Every route has examples for minimal request, success response, and representative failures (§8).
• Every endpoint family has route, sequence, and error diagrams (§9).
• Every tradeoff and compatibility risk is documented (§13.5, §13.6).
• The API doc links to backend and features/flows (See Also).

15. Integration Checklist

• Every route from controllers is documented.
• Every DTO field is documented.
• Every enum value is documented.
• Every response envelope is documented.
• Every error code is documented (12/12).
• Every auth guard and permission is documented.
• Every cache key, queue job, and external call is documented — no cache exists by design.
• Every diagram matches the current code.
• The API doc links to backend and features/flows.

See Also

• Backend doc: /docs/developer/analytics/backend
• Features and flows doc: /docs/developer/analytics/feature
• TDD: not yet published