Loggify Client SDK

A clean, reliable, and secure TypeScript SDK for Loggify Server. Works in Node.js and modern browsers (React, Next.js, NestJS, etc.).

Features

• Ingest single or bulk events (tracing-friendly)
• Offline/slow network resilience with queue + retry + backoff
• Low memory footprint with bounded queue and batch size
• Optional HMAC request signing, Bearer token and API key headers

Install

npm install @cubetiqlabs/loggify-client

Quick start

import { LoggifyClient, createLoggifyClient } from '@cubetiqlabs/loggify-client';

const client = new LoggifyClient({
  baseUrl: 'https://logs.example.com',
  authToken: 'your-jwt',
  source: 'web-app',
  maxBatchSize: 100,
  flushIntervalMs: 1000,
  signWithHmac: { secret: 'shared-secret', header: 'X-Signature' },
});

client.ingest({
  level: 'info',
  message: 'User login',
  metadata: { user_id: '123' },
});

// flush pending events before exit
await client.flush();

Optional: durable persistence with one line

Use a convenience factory that auto-selects the best persistence backend (Node WAL in Node.js, IndexedDB in browsers):

import { createLoggifyClient } from '@cubetiqlabs/loggify-client';

const client = await createLoggifyClient({
  baseUrl: 'https://logs.example.com',
  source: 'my-app',
  persistence: 'auto', // or true, 'node-wal', 'indexeddb'
});

client.ingest('hello durable world');

API

• new LoggifyClient(options)

  • baseUrl (required)
  • apiPath (default /ingest)
  • bulkPath (default /ingest/bulk)
  • authToken, apiKey (optional)
  • source, tenantId (optional defaults)
  • maxBatchSize, flushIntervalMs, maxQueueSize
  • retryBaseDelayMs, retryMaxDelayMs, retryMaxAttempts
  • signWithHmac: { secret, header? }

• ingest(event) – enqueue single event

• trace(event) – alias to ingest for tracing events

• flush() – force flush the queue

  • If persistence is enabled, flush will drain persisted events first, then in-memory queue

Security

• Optional HMAC signing header with timestamp and nonce
• Always uses HTTPS in production environments
• Sensitive values should not be embedded directly in browser apps; prefer server-side token issuance

Notes

• For Next.js/React: this SDK works client-side; for critical paths, consider sending through a server route to keep secrets server-side.
• For NestJS/Node: use directly in services to collect logs/traces.

Tracing: spans with timed steps

Create a span to trace a transaction and measure step durations:

import { LoggifyClient } from '@cubetiqlabs/loggify-client';

const client = new LoggifyClient({
  baseUrl: 'http://localhost:8080',
  apiKey: 'key_abc',
  source: 'app',
});

const span = client.tracer('do spanning transactions').start();

// Do something with long operations
const step1 = span.ingest('Heavy operation executing', { name: 'Test', opts: 100 });
// ... your long task
step1.completed(); // snapshot duration

// Immediate event inside the span
span.ingest({
  level: 'info',
  source: 'app',
  message: 'Hello from other operation',
  metadata: { user_id: '123' },
});

// Finish the span and emit a summary event with timings and steps
span.finish();

Options:

• client.tracer(name, { traceId, spanId, parentSpanId, attributes, autoIngestSteps, stepEventLevel, stepErrorLevel, includeStepsInSpanEvent, minStepDurationMs, bufferSteps })
• step.completed({ error: true }) flags the step and elevates the span status/level.
• autoIngestSteps: false disables immediate step events (summary still emitted).
• minStepDurationMs emits only slow steps (errors always emitted).
• bufferSteps: true holds step events until finish().