Server

The litetics package handles all server-side analytics work: receiving beacons, enriching them with metadata, and determining visitor uniqueness.

import { createEventRequestHandler, createPingRequestHandler, createPingResponse } from 'litetics';

const eventHandler = createEventRequestHandler({
  persist: (data) => {
    /* store load event */
  },
  update: ({ bid, durationMs }) => {
    /* attach duration */
  },
});
const pingHandler = createPingRequestHandler();

app.post('/event', (c) => eventHandler.handle(c.req.raw).then(() => c.body(null, 204)));
app.get('/ping', (c) => pingHandler.handle(c.req.raw).then(createPingResponse));

Two separate handlers. eventHandler.handle() processes POST beacons. pingHandler.handle() processes GET pings.

Input flexibility

Both methods accept a standard Request object, getter functions, or a pre-resolved payload. Pick whichever fits your framework:

// Request object (Hono, Workers, Bun, Deno)
eventHandler.handle(c.req.raw);

// Getter functions (Nuxt Nitro, Fastify)
eventHandler.handle({
  getRequestBody: () => readBody(event),
  getRequestHeader: (name) => getHeader(event, name),
});

// Pre-resolved payload (Express, any framework)
eventHandler.handle({
  requestBody: req.body,
  requestHeaders: { 'user-agent': req.headers['user-agent'] },
});

See the handler reference for full API details, and the integration pages for framework-specific examples.

Error Handling

The handlers do not throw on malformed input:

• Invalid JSON body → logged (if debug: true), event dropped
• Missing or invalid page URL → event dropped
• Unknown event type → logged (if debug: true), event dropped
• Bot user-agent → event dropped

persist and update errors propagate normally. Wrap with try/catch if needed.

No Storage

Litetics never stores data. You provide persist and update callbacks. Common patterns: in-memory array (dev), database insert/update, log stream, analytics platform API call, or a combination.