pl4y-metrics

Reusable TypeScript metrics library for browser clients. It collects context, builds events, batches events, and validates payloads. It does not send network requests.

Install

npm install @pl4yzonellc/pl4y-metrics

Build outputs

• ESM
• CJS
• Type declarations

npm run build

Quick usage

import { createMetricsClient } from '@pl4yzonellc/pl4y-metrics';

const metrics = createMetricsClient({
  tenantId: 'ghoul-portal',
  app: {
    name: 'ghoul-portal-web',
    version: '2.14.0',
    environment: 'prod',
  },
  maxBatchSize: 100,
  autoPageContext: true,
});

metrics.setContext({ referral: 'facebook', subject: 'Math' });
const event = metrics.track('contact_form_submitted');
metrics.incrementCounter(event.eventId, 'calendarSlotChanges', 2);

const payload = metrics.flushBatch();

API

• createMetricsClient(config)
• track(eventName, partialEvent?)
• startTimer(name)
• stopTimer(name) -> durationMs
• incrementCounter(eventId or current event, counterName, by=1)
• setContext(partialContext)
• getBatch() -> MetricsEnvelope (non-destructive)
• flushBatch() -> MetricsEnvelope (destructive)
• reset()

Important architecture rule

This library intentionally has no network layer. Your application is responsible for transport.

Integration snippet (app-level POST)

const payload = metrics.flushBatch();

await fetch('/api/v1/metrics/events:batch', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payload),
});

Run tests

npm test

Exact sample payload

Run:

npm run example:exact

to print the required schema shape shown in examples/exact-payload.ts.