@zetalyx/core

Shared types, configuration, utilities, and constants for the Zetalyx SDK ecosystem.

This package is used internally by @zetalyx/browser, @zetalyx/node, @zetalyx/react, @zetalyx/nextjs, and @zetalyx/react-native. You typically don't need to install it directly.

Installation

npm install @zetalyx/core

What's Inside

Types

import type {
  ZetalyxConfig,         // SDK configuration options
  EventPayload,          // Custom event tracking payload
  ErrorPayload,          // Error tracking payload
  BehaviorPayload,       // User behavior tracking payload
  BatchPayload,          // Batched payload sent to the API
  TransportResult,       // Transport response shape
  ITransport,            // Transport interface
  IQueue,                // Queue interface
} from '@zetalyx/core';

Configuration

import { resolveConfig } from '@zetalyx/core';

const config = resolveConfig({
  apiKey: 'pk_live_...',
  batchSize: 10,         // Flush after 10 events (default)
  flushInterval: 5000,   // Flush every 5s (default)
  maxRetries: 3,         // Retry failed requests 3 times (default)
  debug: false,          // Console debug logging (default)
  enabled: true,         // Enable/disable tracking (default)
});

Utilities

import { generateId, now, normalizeError, safeStringify, createLogger } from '@zetalyx/core';

generateId();                    // UUID v4 string
now();                           // ISO 8601 timestamp
normalizeError(new Error('x'));  // { error_type, message, stacktrace }
safeStringify({ key: 'val' });   // JSON string, handles circular refs
createLogger('Tag', true);       // { debug, warn, error } logger

Constants

import { API_PATHS, DEFAULTS, SDK_VERSION } from '@zetalyx/core';

API_PATHS.EVENTS;     // '/v1/events/batch'
API_PATHS.ERRORS;     // '/v1/errors/batch'
API_PATHS.BEHAVIORS;  // '/v1/behaviors/batch'
DEFAULTS.BATCH_SIZE;  // 10
DEFAULTS.FLUSH_MS;    // 5000

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your Zetalyx API key (pk_live_... or sk_live_...) | | endpoint | string | https://api.zetalyx.com | API endpoint URL | | batchSize | number | 10 | Events buffered before auto-flush | | flushInterval | number | 5000 | Auto-flush interval in ms | | maxRetries | number | 3 | Max retries on 5xx/network errors | | debug | boolean | false | Enable console debug logging | | enabled | boolean | true | Master kill switch for all tracking | | beforeSend | (event) => event \| null | — | Transform or filter events before sending | | headers | Record<string, string> | {} | Custom headers on every request |

License

MIT