Hyperse
  • Pricing
  • FAQs
Newsletter

Subscribe to our newsletter

Receive weekly updates with latest collections and exclusive offers, straight to your inbox.

Hyperse

Headless commerce solutions for brands, developers, and modern ecommerce teams.

Explore

  • Home
  • About Us
  • Partners
  • FAQs

Legal & resources

  • Proposal
  • Privacy Policy
  • Terms & Conditions

© 2026 Hyperse. All rights reserved.


  1. Home
  2. Vendure Plugins
  3. hps-plugin-metrics
hps-plugin-metrics

hps-plugin-metrics

By Yingchun Tian

hps-plugin-metrics is a Metrics plugin in the Hub Report group.hps-plugin-metrics provides Metrics plugin capabilities for Hub Report. Reporting, metrics, analytics, and business insights. It is especially useful for analytics workflows.

CoreVendure Plugins

Specifications

Technical details and package information for this product.

Package

@hyperse-hub/hps-plugin-metrics

Support by

Yingchun Tian

Support languages

TypeScript, JavaScript, Prolog, CSS, Shell

Integration type

Core

Category

Vendure Plugins

Compatible with

^3.0.0

Latest version

1.0.6

Downloads

0

Repository

https://github.com/hyperse-hub/hub-report

Last published

July 14, 2026

Description
Changelog
loading...

@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)

ItemValue
Directorypackages/plugin-metrics
NPM name@hyperse-hub/hps-plugin-metrics
Plugin classHpsPluginMetrics
Entry filesrc/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', // optional: defaultRoute: '/metrics', }), 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)

OptionTypeDescription
metricsMetricCalculationStrategy[]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(), // ...your MetricCalculationStrategy implementations ], });

Default metrics (src/strategy)

ClasscodeMeaning per time bucket & language
NrOfOrdersMetricnr-of-ordersOrder count
AverageOrderValueMetricaovMean totalWithTax (rounded int)
OrderTotalSalesValueMetricorder-total-sales-valueSum 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/)

PathRole
hps-metrics.plugin.tsVendure plugin: GraphQL schema/resolver, providers, custom field + order interceptor, admin extension registration
index.tsPackage exports
constants.tsloggerCtx, injection token, cache TTL
types.ts / types.merging.tsInit options + CustomOrderFields.languageCode merge for TypeScript
api/schema/admin-api-extensions.tsAdmin API SDL
api/resolvers/metrics-admin.resolver.tshpsMetricSummary, hpsOrderSummary
services/metrics.service.tsData load, aggregation, cache, order summary math
strategy/*Metric interfaces, defaults, shared utils
interceptors/add-language-interceptor.tsSets languageCode custom field when adding first item
extensions/*Menu extension metadata for HpsPluginAdmin
generated-admin-types.tsGraphQL-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.

On this page

  • @hyperse-hub/hps-plugin-metrics
    • Package naming (see PLUGIN_NAMING_GUIDE.md at repo root)
    • What it does
    • Requirements
    • Installation
    • Configuration (HpsPluginMetrics.init)
    • Default metrics (src/strategy)
    • Money units (IMPORTANT)
    • Time ranges (MetricsService)
    • Extending: MetricCalculationStrategy
    • Source layout (src/)
    • GraphQL (admin)
    • Development