open-index/open-npm huggingface dataset:
npm package: @pl4yzonellc/pl4y-metrics
Description: Framework-agnostic browser metrics payload builder and validator
Latest version: 0.2.1

# 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

```bash
npm install @pl4yzonellc/pl4y-metrics
```

## Build outputs

- ESM
- CJS
- Type declarations

```bash
npm run build
```

## Quick usage

```ts
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)

```ts
const payload = metrics.flushBatch();

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

## Run tests

```bash
npm test
```

## Exact sample payload

Run:

```bash
npm run example:exact
```

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