@hyperse-hub/hps-plugin-metrics
Vendure plugin for the Hub Report stack: order-based metrics for Hyperse Admin (time-series charts, order/revenue summaries) plus an admin menu entry wired through @hyperse-hub/hps-plugin-admin.
Package naming (see PLUGIN_NAMING_GUIDE.md at repo root)
| Item | Value |
|---|
| Directory | packages/plugin-metrics |
| NPM name | @hyperse-hub/hps-plugin-metrics |
| Plugin class | HpsPluginMetrics |
| Entry file | src/hps-metrics.plugin.ts |
What it does
- Admin GraphQL:
hpsMetricSummary (bucketed metrics by day / ISO week / month) and hpsOrderSummary (today, yesterday, this week, this month with period-over-period growth). Both require Permission.ReadOrder.
- Channel-scoped orders: Metrics load orders placed in the active channel, paginated in batches of 1000.
- Language breakdown: Each bucket can split values by
Order.customFields.languageCode (Vendure language codes such as en, en_GB, not geographic countries). The plugin registers that custom field and an order interceptor that sets it on first line item if missing (from RequestContext.languageCode, default en).
- Caching:
hpsMetricSummary results are cached in Vendure’s CacheService for 15 minutes (METRICS_CACHE_TTL_MS). Use input.refresh: true to bypass. Cache key includes channel, interval, onlyPaidOrder, metric set fingerprint, and the end-of-day anchor date.
- Admin UI: On bootstrap (server process), registers merged admin extensions (route
/metrics, template hyperse-hub/hps-plugin-metrics/metrics). Requires HpsPluginAdmin in the same Vendure config.
Requirements
- Vendure
>=3.0.0 (plugin compatibility: '>=3.0.0').
- @hyperse-hub/hps-plugin-admin — the metrics plugin imports it and registers menu extensions through
AdminExtensionService.
Installation
Add the plugin (and admin host) to your Vendure plugins array. Minimal pattern (see e2e/fixtures/plugin-metrics-e2e-environment.ts and config/dev-server.ts in this package):
import { HpsPluginAdmin } from '@hyperse-hub/hps-plugin-admin';
import { HpsPluginMetrics } from '@hyperse-hub/hps-plugin-metrics';
export const config = {
plugins: [
HpsPluginAdmin.init({
domainUrl: 'https://your-admin-origin',
}),
HpsPluginMetrics.init({}),
],
};
Public API is re-exported from the package root (./index.js / dist/index.d.ts): plugin class, constants, types, MetricsService, and metric strategy classes.
Configuration (HpsPluginMetrics.init)
| Option | Type | Description |
|---|
metrics | MetricCalculationStrategy[] | Replace the default metric calculators. Defaults to NrOfOrdersMetric, AverageOrderValueMetric, OrderTotalSalesValueMetric. |
Example: keep defaults (empty init({})) or supply a custom list:
HpsPluginMetrics.init({
metrics: [
new NrOfOrdersMetric(),
new AverageOrderValueMetric(),
new OrderTotalSalesValueMetric(),
],
});
Default metrics (src/strategy)
| Class | code | Meaning per time bucket & language |
|---|
NrOfOrdersMetric | nr-of-orders | Order count |
AverageOrderValueMetric | aov | Mean totalWithTax (rounded int) |
OrderTotalSalesValueMetric | order-total-sales-value | Sum of totalWithTax |
Money units (IMPORTANT)
- Backend unit: Money values produced by this plugin come from Vendure
Order.totalWithTax, which is stored/returned as an integer in minor units (the smallest currency unit; e.g. USD cents).
- Affected fields / metrics:
- Metric
aov: computed from totalWithTax and returned in minor units.
- Metric
order-total-sales-value: sum of totalWithTax returned in minor units.
hpsOrderSummary.totalRevenue / previousPeriodRevenue: sums of totalWithTax returned in minor units.
- UI display: Convert minor units → display amount using the currency’s fraction digits.
- For common 2-decimal currencies (USD/EUR), this is typically equivalent to dividing by 100 and formatting as currency.
- Do not hardcode
/ 100 for all currencies (e.g. JPY has 0 fraction digits).
When HpsMetricSummaryInput.onlyPaidOrder is true, strategies use filterOrders (src/strategy/metric-utils.ts) to keep only orders in: PaymentSettled, Shipped, PartiallyShipped, Delivered, PartiallyDelivered (excludes e.g. Cancelled).
hpsOrderSummary always uses all orders in range (no paid-only flag).
Time ranges (MetricsService)
- DAILY: last 30 calendar days (through end of today).
- WEEKLY: last 26 ISO weeks.
- MONTHLY: last 12 months.
Week boundaries for data buckets use ISO week (startOfISOWeek). This week in hpsOrderSummary uses date-fns startOfWeek with weekStartsOn: 1 (Monday).
Extending: MetricCalculationStrategy
Implement MetricCalculationStrategy (src/strategy/metric-calculation-strategy.ts): code, getTitle(ctx), and calculateEntry(ctx, data, { interval, onlyPaidOrder }) returning a HpsMetricSummaryEntry (label, languageCodes, entry with aligned rows). Reuse metric-utils (filterOrders, splitOrdersByLanguageCode, sortedLanguageMetricRows, labelFormat) for consistent behavior.
Source layout (src/)
| Path | Role |
|---|
hps-metrics.plugin.ts | Vendure plugin: GraphQL schema/resolver, providers, custom field + order interceptor, admin extension registration |
index.ts | Package exports |
constants.ts | loggerCtx, injection token, cache TTL |
types.ts / types.merging.ts | Init options + CustomOrderFields.languageCode merge for TypeScript |
api/schema/admin-api-extensions.ts | Admin API SDL |
api/resolvers/metrics-admin.resolver.ts | hpsMetricSummary, hpsOrderSummary |
services/metrics.service.ts | Data load, aggregation, cache, order summary math |
strategy/* | Metric interfaces, defaults, shared utils |
interceptors/add-language-interceptor.ts | Sets languageCode custom field when adding first item |
extensions/* | Menu extension metadata for HpsPluginAdmin |
generated-admin-types.ts | GraphQL-generated types (run yarn codegen from this package) |
GraphQL (admin)
**hpsMetricSummary(input: HpsMetricSummaryInput!)**: interval (DAILY WEEKLY MONTHLY), optional onlyPaidOrder, optional refresh.
**hpsOrderSummary**: array for TODAY, YESTERDAY, THIS_WEEK, THIS_MONTH with totalOrder, totalRevenue, previous period counts/revenue, and growthOrder / growthRevenue as **percentage change** vs previous period (numeric percent, e.g. 10 ≈ 10% growth), plus dateRange ISO strings.
Development
Use the workspace scripts in this package’s package.json (serve, build, test, etc.) from the monorepo root with Yarn 4 workspaces.
**yarn build**: build:server (hps_tsc from src/index.ts) + build:ui (admin bundle).
**yarn codegen**: refresh generated-admin-types.ts from admin-api-extensions.ts.
**yarn serve**: local dev server (config/dev-server.ts) with metrics + admin defaults.