@nexussdk/core 0.0.1

package/src/http-client.ts

@@ -0,0 +1,202 @@
+/**
+ * @fileoverview Resilient HTTP client with exponential backoff and jitter.
+ * Zero external dependencies — uses only native browser fetch and AbortController.
+ * @module @nexus/core/http-client
+ */
+
+/**
+ * Options for configuring a single HTTP request with retry behaviour.
+ *
+ * @example
+ * const opts: HttpClientOptions = {
+ *   url: 'https://api.nexus.dev/api/v1/flags/eval',
+ *   method: 'GET',
+ *   headers: { Authorization: 'Bearer pk_live_...' },
+ *   timeoutMs: 3000,
+ *   maxRetries: 3,
+ * };
+ */
+export interface HttpClientOptions {
+  /** Request URL. */
+  url: string;
+  /** HTTP method. Defaults to 'GET'. */
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  /** Request headers. */
+  headers?: Record<string, string>;
+  /** Request body (will be JSON-serialized if object). */
+  body?: unknown;
+  /** Request timeout in milliseconds. Defaults to 5000ms. */
+  timeoutMs?: number;
+  /** Maximum retry attempts on 5xx / network errors. Defaults to 3. */
+  maxRetries?: number;
+  /** Base delay in milliseconds for exponential backoff. Defaults to 1000ms. */
+  retryBaseMs?: number;
+  /** Maximum backoff delay in milliseconds. Defaults to 30000ms. */
+  retryMaxMs?: number;
+  /** Optional AbortSignal for external cancellation. */
+  signal?: AbortSignal;
+}
+
+/**
+ * Result of a successful HTTP fetch.
+ *
+ * @template T The expected response body type.
+ */
+export interface HttpClientResult<T> {
+  /** Parsed response body. */
+  data: T;
+  /** HTTP status code. */
+  status: number;
+  /** Response headers. */
+  headers: Headers;
+}
+
+/**
+ * Computes the exponential backoff sleep duration with full random jitter.
+ * Formula: sleep = random(0, min(maxMs, baseMs * 2^attempt))
+ *
+ * @param attempt - Zero-based retry attempt index.
+ * @param baseMs - Base delay in milliseconds.
+ * @param maxMs - Maximum delay cap in milliseconds.
+ * @returns Sleep duration in milliseconds.
+ *
+ * @example
+ * const delay = computeBackoffMs(2, 1000, 30000); // ~0-4000ms
+ */
+export function computeBackoffMs(attempt: number, baseMs = 1000, maxMs = 30_000): number {
+  const exponential = baseMs * Math.pow(2, attempt);
+  const capped = Math.min(maxMs, exponential);
+  // Full jitter: random value in [0, capped]
+  return Math.random() * capped;
+}
+
+/**
+ * Sleeps for the given number of milliseconds.
+ *
+ * @param ms - Delay in milliseconds.
+ * @param signal - Optional AbortSignal to cancel the sleep.
+ * @returns Promise that resolves after delay, or rejects if aborted.
+ */
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new DOMException('Aborted', 'AbortError'));
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => {
+      clearTimeout(timer);
+      reject(new DOMException('Aborted', 'AbortError'));
+    });
+  });
+}
+
+/**
+ * Determines if an HTTP response status warrants a retry attempt.
+ *
+ * @param status - HTTP status code.
+ * @returns `true` if the request should be retried.
+ */
+function isRetryableStatus(status: number): boolean {
+  return status >= 500 || status === 429;
+}
+
+/**
+ * Performs a resilient HTTP fetch with exponential backoff and jitter.
+ * Automatically retries on network failures and 5xx/429 responses.
+ *
+ * @template T The expected response body type.
+ * @param options - Request configuration options.
+ * @returns Promise resolving to {@link HttpClientResult}.
+ * @throws {Error} When all retry attempts are exhausted or request is aborted.
+ *
+ * @example
+ * const result = await fetchWithRetry<BatchFlagEvaluation>({
+ *   url: 'https://api.nexus.dev/api/v1/flags/eval',
+ *   method: 'GET',
+ *   headers: { Authorization: 'Bearer pk_live_...' },
+ *   timeoutMs: 3000,
+ *   maxRetries: 3,
+ * });
+ * console.log(result.data); // { checkout_v2: { enabled: true, ... } }
+ */
+export async function fetchWithRetry<T = unknown>(
+  options: HttpClientOptions,
+): Promise<HttpClientResult<T>> {
+  const {
+    url,
+    method = 'GET',
+    headers = {},
+    body,
+    timeoutMs = 5_000,
+    maxRetries = 3,
+    retryBaseMs = 1_000,
+    retryMaxMs = 30_000,
+    signal: externalSignal,
+  } = options;
+
+  let lastError: Error = new Error('Request failed');
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    // Abort if external signal is already triggered
+    if (externalSignal?.aborted) {
+      throw new DOMException('Request aborted by caller.', 'AbortError');
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+    // Merge external abort signal
+    externalSignal?.addEventListener('abort', () => controller.abort());
+
+    try {
+      const requestInit: RequestInit = {
+        method,
+        headers: {
+          'Content-Type': 'application/json',
+          ...headers,
+        },
+        signal: controller.signal,
+      };
+
+      if (body !== undefined) {
+        requestInit.body = typeof body === 'string' ? body : JSON.stringify(body);
+      }
+
+      const response = await fetch(url, requestInit);
+      clearTimeout(timeoutId);
+
+      if (response.ok) {
+        const data = (await response.json()) as T;
+        return { data, status: response.status, headers: response.headers };
+      }
+
+      // Non-ok response: check if retryable
+      if (isRetryableStatus(response.status) && attempt < maxRetries) {
+        lastError = new Error(`HTTP ${response.status}: ${response.statusText}`);
+        const delay = computeBackoffMs(attempt, retryBaseMs, retryMaxMs);
+        await sleep(delay, externalSignal);
+        continue;
+      }
+
+      // Non-retryable error (400, 401, 403, 404, etc.)
+      const errorBody = await response.text().catch(() => '');
+      throw new Error(`HTTP ${response.status}: ${errorBody}`);
+    } catch (err) {
+      clearTimeout(timeoutId);
+
+      if (err instanceof DOMException && err.name === 'AbortError') {
+        throw err; // Propagate abort without retry
+      }
+
+      lastError = err instanceof Error ? err : new Error(String(err));
+
+      if (attempt < maxRetries) {
+        const delay = computeBackoffMs(attempt, retryBaseMs, retryMaxMs);
+        await sleep(delay, externalSignal);
+      }
+    }
+  }
+
+  throw lastError;
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Main entry point for @nexussdk/core.
+ * Re-exports the resilient HTTP client, in-memory RingBuffer, environment resolver, and safe JSON parser.
+ *
+ * @example
+ * import { fetchWithRetry, RingBuffer, resolveApiKey, safeStringify } from '@nexussdk/core';
+ */
+
+export { fetchWithRetry, computeBackoffMs } from './http-client.js';
+export type { HttpClientOptions, HttpClientResult } from './http-client.js';
+
+export { RingBuffer } from './ring-buffer.js';
+
+export { resolveApiKey, resolveBaseUrl } from './env-resolver.js';
+
+export { safeStringify, safeParse } from './safe-json.js';

package/src/ring-buffer.ts

@@ -0,0 +1,148 @@
+/**
+ * @fileoverview Fixed-capacity ring buffer with FIFO eviction under pressure.
+ * Used by SDK Tracker for bounded breadcrumb and telemetry event storage.
+ * @module @nexus/core/ring-buffer
+ */
+
+/**
+ * A fixed-capacity circular buffer that drops the oldest entry when full.
+ * Never causes memory leaks or starvation of host applications.
+ *
+ * @template T The type of items stored in the buffer.
+ *
+ * @example
+ * const buffer = new RingBuffer<string>(3);
+ * buffer.push('a'); // [a]
+ * buffer.push('b'); // [a, b]
+ * buffer.push('c'); // [a, b, c]
+ * buffer.push('d'); // [b, c, d] — 'a' evicted (FIFO)
+ * buffer.toArray();  // ['b', 'c', 'd']
+ */
+export class RingBuffer<T> {
+  private readonly capacity: number;
+  private readonly buffer: Array<T | undefined>;
+  private head = 0;   // Points to the next write position
+  private count = 0;  // Current number of items
+
+  /**
+   * Creates a new RingBuffer with the given capacity.
+   *
+   * @param capacity - Maximum number of items to retain. Must be >= 1.
+   * @throws {RangeError} If capacity is less than 1.
+   *
+   * @example
+   * const breadcrumbBuffer = new RingBuffer<Breadcrumb>(20);
+   */
+  constructor(capacity: number) {
+    if (capacity < 1) {
+      throw new RangeError(`RingBuffer capacity must be >= 1, got ${capacity}`);
+    }
+    this.capacity = capacity;
+    this.buffer = new Array<T | undefined>(capacity).fill(undefined);
+  }
+
+  /**
+   * Appends an item to the buffer.
+   * If the buffer is at capacity, the oldest item is silently dropped.
+   *
+   * @param item - The item to insert.
+   *
+   * @example
+   * buffer.push({ timestamp: Date.now(), category: 'ui.click', message: 'Clicked #btn' });
+   */
+  push(item: T): void {
+    this.buffer[this.head] = item;
+    this.head = (this.head + 1) % this.capacity;
+    if (this.count < this.capacity) {
+      this.count++;
+    }
+  }
+
+  /**
+   * Returns all stored items in chronological order (oldest first).
+   *
+   * @returns Ordered array of stored items.
+   *
+   * @example
+   * const breadcrumbs = buffer.toArray(); // [{...}, {...}]
+   */
+  toArray(): T[] {
+    if (this.count === 0) return [];
+
+    const result: T[] = [];
+    if (this.count < this.capacity) {
+      // Buffer not yet full — read from index 0 to head-1
+      for (let i = 0; i < this.count; i++) {
+        result.push(this.buffer[i] as T);
+      }
+    } else {
+      // Buffer full — oldest item is at `head`
+      for (let i = 0; i < this.capacity; i++) {
+        result.push(this.buffer[(this.head + i) % this.capacity] as T);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Returns the current number of items in the buffer.
+   *
+   * @returns Item count (0 to capacity).
+   *
+   * @example
+   * console.log(buffer.size); // 3
+   */
+  get size(): number {
+    return this.count;
+  }
+
+  /**
+   * Returns the maximum capacity of the buffer.
+   *
+   * @returns Buffer capacity.
+   *
+   * @example
+   * console.log(buffer.maxCapacity); // 20
+   */
+  get maxCapacity(): number {
+    return this.capacity;
+  }
+
+  /**
+   * Checks if the buffer is currently at full capacity.
+   *
+   * @returns `true` if the buffer is full.
+   *
+   * @example
+   * if (buffer.isFull) console.log('Oldest breadcrumb will be evicted on next push.');
+   */
+  get isFull(): boolean {
+    return this.count === this.capacity;
+  }
+
+  /**
+   * Removes all items from the buffer and resets internal state.
+   *
+   * @example
+   * buffer.clear(); // buffer is now empty
+   */
+  clear(): void {
+    this.buffer.fill(undefined);
+    this.head = 0;
+    this.count = 0;
+  }
+
+  /**
+   * Peeks at the most recently added item without removing it.
+   *
+   * @returns The last item pushed, or `undefined` if empty.
+   *
+   * @example
+   * const last = buffer.peek(); // most recent item
+   */
+  peek(): T | undefined {
+    if (this.count === 0) return undefined;
+    const lastIndex = (this.head - 1 + this.capacity) % this.capacity;
+    return this.buffer[lastIndex];
+  }
+}

package/src/safe-json.ts

@@ -0,0 +1,134 @@
+/**
+ * @fileoverview Circular-reference-safe JSON serializer using WeakSet tracking.
+ * Prevents TypeError crashes when serializing objects with circular references.
+ * @module @nexus/core/safe-json
+ */
+
+/**
+ * Recursively sanitizes an object for JSON serialization by replacing
+ * circular references with the string "[Circular]".
+ *
+ * @param value - The value to sanitize.
+ * @param seen - WeakSet tracking visited objects (used internally for recursion).
+ * @param depth - Current recursion depth.
+ * @param maxDepth - Maximum allowed recursion depth.
+ * @returns A serialization-safe copy of the value.
+ */
+function sanitizeForSerialization(
+  value: unknown,
+  seen: WeakSet<object>,
+  depth: number,
+  maxDepth: number,
+): unknown {
+  if (depth > maxDepth) {
+    return '[MaxDepthExceeded]';
+  }
+
+  if (value === null || value === undefined) {
+    return value;
+  }
+
+  if (typeof value !== 'object' && typeof value !== 'function') {
+    // Primitive value: string, number, boolean, bigint, symbol
+    if (typeof value === 'bigint') {
+      return value.toString(); // JSON cannot handle BigInt natively
+    }
+    if (typeof value === 'symbol') {
+      return value.toString();
+    }
+    if (typeof value === 'function') {
+      return '[Function]';
+    }
+    return value;
+  }
+
+  // Handle Error objects specially — preserve message and stack
+  if (value instanceof Error) {
+    return {
+      name: value.name,
+      message: value.message,
+      stack: value.stack,
+    };
+  }
+
+  // Circular reference detection
+  if (seen.has(value as object)) {
+    return '[Circular]';
+  }
+  seen.add(value as object);
+
+  // Handle Arrays
+  if (Array.isArray(value)) {
+    const result = value.map((item) =>
+      sanitizeForSerialization(item, seen, depth + 1, maxDepth),
+    );
+    seen.delete(value as object);
+    return result;
+  }
+
+  // Handle plain Objects
+  const result: Record<string, unknown> = {};
+  for (const key of Object.keys(value as object)) {
+    const propValue = (value as Record<string, unknown>)[key];
+    result[key] = sanitizeForSerialization(propValue, seen, depth + 1, maxDepth);
+  }
+  seen.delete(value as object);
+  return result;
+}
+
+/**
+ * Serializes a value to a JSON string, gracefully handling:
+ * - Circular references (replaced with "[Circular]")
+ * - BigInt values (converted to string)
+ * - Symbol values (converted to string)
+ * - Function values (replaced with "[Function]")
+ * - Deep nesting (capped at maxDepth, replaced with "[MaxDepthExceeded]")
+ *
+ * @param value - Any value to serialize.
+ * @param maxDepth - Maximum recursion depth. Defaults to 8.
+ * @returns JSON string representation of the value.
+ *
+ * @example
+ * const obj: Record<string, unknown> = { name: 'test' };
+ * obj['self'] = obj; // circular reference
+ * const json = safeStringify(obj);
+ * // '{"name":"test","self":"[Circular]"}'
+ *
+ * @example
+ * const err = new Error('Something failed');
+ * const json = safeStringify({ error: err, code: 500 });
+ * // '{"error":{"name":"Error","message":"Something failed","stack":"..."},"code":500}'
+ */
+export function safeStringify(value: unknown, maxDepth = 8): string {
+  const seen = new WeakSet<object>();
+  const sanitized = sanitizeForSerialization(value, seen, 0, maxDepth);
+  try {
+    return JSON.stringify(sanitized);
+  } catch {
+    // Absolute last resort fallback
+    return JSON.stringify({ error: '[SerializationFailed]' });
+  }
+}
+
+/**
+ * Safely parses a JSON string without throwing on invalid input.
+ *
+ * @param input - The JSON string to parse.
+ * @param fallback - Value to return if parsing fails. Defaults to `null`.
+ * @returns Parsed value or fallback.
+ *
+ * @example
+ * const data = safeParse<{ id: string }>('{"id":"123"}');
+ * // { id: '123' }
+ *
+ * @example
+ * const data = safeParse<unknown>('{{invalid json}}', null);
+ * // null
+ */
+export function safeParse<T = unknown>(input: string, fallback: T | null = null): T | null {
+  try {
+    return JSON.parse(input) as T;
+  } catch {
+    return fallback;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs', 'iife'],
+  globalName: 'NexusCore',
+  dts: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  minify: true,
+  treeshake: true,
+  target: 'es2022',
+  outExtension({ format }) {
+    return {
+      js: format === 'esm' ? '.mjs' : format === 'cjs' ? '.cjs' : '.global.js',
+    };
+  },
+});