Analytics Service Reference

Module

src/data/analytics/analytics.service.ts

Factory

createAnalyticsService(deps: AnalyticsServiceDeps): AnalyticsService

Dependencies

Dep	Type	Description
OrderModel	Mongoose model	Source of all order aggregation
cache	ICachePort	Valkey/Redis; 60-second result TTL
logger	{ warn }	Optional warning logger

Methods

getRevenueOverview(ctx, period)

Computes gross revenue, order count, average order value, and period-over-period delta for a tenant.

Output: RevenueOverviewReport

• period.grossRevenueCents — sum of totalCents for submitted/completed orders
• period.orderCount — count of orders in window
• period.avgOrderValueCents — gross / count (0 when no orders)
• delta.grossRevenuePct — % change vs prior equal-length period (null when no prior data)
• delta.orderCountPct — same for order count
• dailyBreakdown — array of { date: string, revenueCents, orderCount } for each day in the period

getSalesVelocity(ctx, period)

Aggregates order velocity by day and computes a DOW × hour heatmap.

Output: SalesVelocityReport

• ordersPerDay — { date, orderCount }[]
• dowHeatmap — 7 × 24 matrix, [dayOfWeek][hour] = order count
• slowDayCallout — the DOW with the lowest average orders, plus its lowest-average hour

getProductPerformance(ctx, period)

Unwinds order line items and groups by product to rank revenue, quantity, and velocity.

Output: ProductPerformanceReport

• products — array sorted by revenue descending: { productId, name, revenueCents, unitsSold, orderCount, avgOrderValueCents, isTopRevenue, isTopVolume, isSlowMover }

Stubs (reports 4–10)

Methods getCustomerInsights, getCouponImpact, getTimeOfDayHeatmap, getInventoryTurnover, getRefundCancelRate, getChannelPerformance, getGeographicDistribution throw AnalyticsNotYetImplementedError with a specSection pointer to docs/specs/2026-04-26-analytics.md.

---

Analytics Share-Link Service Reference

Module: src/data/analytics-share-link/analytics-share-link.service.ts

createAnalyticsShareLinkService(deps: AnalyticsShareLinkServiceDeps): AnalyticsShareLinkService

Token format

base64url(JSON payload) + '.' + base64url(HMAC-SHA256 signature)

Payload:

{ reportType: string, tenantId: string, period: { from: string, to: string }, exp: number }

Methods

• generateShareLink(params) — signs a token and returns { url, expiresAt, reportType, period }
• verifyShareLinkToken(raw) — returns { ok: true, payload } or { ok: false, reason }

Reason codes: 'expired', 'tampered', 'invalid', 'config-missing'.