Frank
Repositories
1
 Projects Packages
12

@frank/analytics (0.1.0)

Published 2026-09-26 16:06:51 +10:00 by steve

Installation

@frank:registry=
npm install @frank/analytics@0.1.0
"@frank/analytics": "0.1.0"

About this package

@frank/analytics

The Meta monitoring read model, ported from Blockwise src/lib/meta-monitor: it builds the Results/Home reporting payload from Meta Graph reads only, caches it as a snapshot with etag/TTL, and provides the chart, pacing, suburb and budget math. Nothing here writes to Meta; publish and mutation stay in the product.

Public API

Everything is exported from the package root:

  • getMetaMonitorData / getResultsPayload: build the live payload (or the labelled sample when nothing is connected).
  • loadReportingSnapshot / refreshReportingSnapshot / reportingRangeKey / isMatchingEtag: the cached read-through layer.
  • queueReportingRefresh(es): durable refresh requests (dedupe buckets kept).
  • buildSampleMetaMonitorPayload: the demo fixture.
  • fetchMetaInsightRows and friends: raw Meta Graph reads (15s deadline, pagination, no-store).
  • Math: CHART_METRICS, buildResultsHierarchy, safeRate, safeCpl, calculateBudgetPacing, detectCreativeFatigue, budget alerts, owned performance persistence, suburb resolution.

Config

configFromEnv() (the only env reader) yields AnalyticsConfig: sample flag, budget, site URL, graph version, dev warnings, and the Blockwise table names. Pass DEFAULT_CONFIG in tests. DB access goes through the ReadDb/ServiceDb seam (a Supabase client matches); email and queue access go through ports.

Usage

import { configFromEnv, loadReportingSnapshot } from "@frank/analytics";

const { snapshot, needsRefresh } = await loadReportingSnapshot({
  supabase, workspaceId, range: "last_7",
  ports: { config: configFromEnv(process.env), provider: "meta", loadProviderTokens, budgetAlert },
});

Dependencies

Dependencies

ID Version
@sentry/core ^10.69.0

Development dependencies

ID Version
@types/node ^22.0.0
Details
npm
2026-09-26 16:06:51 +10:00
67
54 KiB
Assets (1)
analytics-0.1.0.tgz 54 KiB
Versions (2) View all
0.2.0 2026-10-04
0.1.0 2026-09-26