@happyvertical/analytics

中文文档
0.113.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 5250

Unified analytics interface for Google Analytics 4, Plausible, and more

原始使用文档

@happyvertical/analytics

Unified analytics interfaces for Google Analytics 4, Plausible, and Matomo.

Matomo reports

Date-dimension reports use VisitsSummary.get with period=day. Each date in Matomo's response produces one report row, including dates represented by an empty array or empty record. Empty days have zero metrics; populated days retain their counts. The provider does not invent dates absent from the response.

Page reports use Actions.getPageUrls. For compatibility, pagePath and unifiedPagePathScreen return Matomo's full page URL when supplied, falling back to its label. Consumers matching local content paths should parse the URL at their application boundary.

activeUsers reads nb_uniq_visitors or nb_users. When Matomo omits both, the current provider returns zero; this means the visitor metric is unavailable, not proof that there were no visitors. nb_visits maps to sessions and must not be substituted for unique visitors. Page-view metrics read nb_hits or nb_pageviews. Consumers should use the available metrics and distinguish an unavailable visitor count from an observed zero.

Run package validation with pnpm --filter @happyvertical/analytics test and pnpm exec turbo run build --filter=@happyvertical/analytics.

Exact timestamp interval aggregates

runIntervalReport(propertyId, { interval: { startTime, endTime, timeZone }, metrics }) is separate from calendar-date runReport. It describes the exact half-open interval [startTime, endTime): the end instant is excluded. Timestamps require seconds and an explicit offset (Z or +/-HH:MM), with up to three fractional digits. The explicit IANA timeZone provides context; the timestamp offsets define the instants, including during DST folds. Empty/reversed intervals, invalid calendar timestamps, unknown-offset -00:00, unknown zones and empty or duplicate metrics reject with RangeError before provider access.

Check getCapabilities().timestampIntervalReporting and the optional method before calling; absent capabilities/methods mean unsupported. Matomo advertises { precision: 'utc-calendar-days', metrics: ['screenPageViews'] }. It verifies the property's timezone from provider metadata and supports only UTC properties with both instants at UTC midnight. Intervals ending after the current time return unavailable (interval-incomplete) without a provider report. It requests Actions.get once for the inclusive calendar range ending the day before the exclusive boundary. This supports reproducible whole-day or quarterly pageview totals without summing visitor counts. Non-UTC properties, DST days, partial days and other metrics return status: 'unsupported'; unknown property timezone returns unavailable.

Only status: 'available' contains metrics, including an observed value '0'. Missing/malformed provider pageviews return status: 'unavailable', never zero. Authentication, network and provider failures reject normally. GA4 and Plausible currently advertise false and return unsupported precision without a request. No adapter silently converts arbitrary timestamps to calendar dates. Existing calendar reports retain their behavior and their documented availability limits.

const capabilities = await analytics.getCapabilities();
if (capabilities.timestampIntervalReporting && analytics.runIntervalReport) {
  const result = await analytics.runIntervalReport('site-id', {
    interval: {
      startTime: '2026-07-01T00:00:00Z',
      endTime: '2026-10-01T00:00:00Z',
      timeZone: 'UTC',
    },
    metrics: [{ name: 'screenPageViews' }],
  });
  if (result.status === 'available') console.log(result.metrics);
}

Provider boundary contract: Matomo Reporting API uses inclusive calendar ranges in the property's timezone. Plausible's documented timestamp support does not by itself establish this API's exact half-open precision guarantees, so it remains unsupported here.

版本与发布记录

@happyvertical/analytics 共发布 132 个版本,首次发布于 2026/06/23;过去 12 个月发布了 132 个版本。

版本发布日期距今
0.113.1latest2026/11/17今天
0.113.02026/11/152 天前
0.112.32026/11/134 天前
0.112.22026/11/125 天前
0.112.12026/11/125 天前
0.112.02026/11/125 天前

关于 @happyvertical/analytics 的常见问题

@happyvertical/analytics 是什么?

Unified analytics interface for Google Analytics 4, Plausible, and more

如何安装 @happyvertical/analytics?

在项目目录运行 npm install @happyvertical/analytics,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 have-analytics-context,可以用 npx have-analytics-context 直接运行。

@happyvertical/analytics 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/analytics 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/analytics 可以商用吗?

@happyvertical/analytics 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/analytics 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/analytics 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,250 次,日均约 175 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/analytics 还在维护吗?

最新版本 0.113.1 发布于 2026/11/17(今天);至今共发布 132 个版本,其中过去 12 个月发布了 132 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。