VANTAGE
Documentation

Standalone Sonar SDK (@xtnd-dynamics/xtnd-sonar-sdk)

Repository: XTND-DYNAMICS/xtnd-sonar-sdk
NPM Package: @xtnd-dynamics/xtnd-sonar-sdk

1. Overview

@xtnd-dynamics/xtnd-sonar-sdk is the standalone, zero-dependency client library for AI observability, token economics, and quota tracking.

Unlike the monorepo package @xtnd/vantage-sonar (which relies on monorepo peer dependencies like @xtnd/vantage-sync-manager), this standalone library is designed to be installed as an isolated dependency into external repositories (such as LaoGPT, EvergreenAI, or backend microservices).

2. Built-In Standalone Storage Manager (SonarStorageManager)

The standalone SDK includes a self-contained in-memory buffer:

  • Retains events in memory without external database requirements.
  • Uses flushBatch() every 10 seconds to send batched telemetry to https://api.sonar.vantage.xgi.io.
  • Dispatches P0_CRITICAL events (such as quota exhaustion) immediately using flushImmediate() with keepalive: true.

3. Core Classes & Exported Utilities

import {
  sonar,                  // Pre-instantiated global singleton
  SonarClient,            // Custom client constructor
  calculateTokenCost,     // Token economics & caching ROI calculator
  parseOpenAIResponse,    // OpenAI header & usage parser
  parseAnthropicResponse, // Anthropic header & cache reader parser
  parseGeminiResponse,    // Google Gemini usage parser
  MODEL_PRICING_TABLE     // Master token pricing dictionary
} from '@xtnd-dynamics/xtnd-sonar-sdk';

4. Usage Examples

4.1 Calculating Prompt Cache Savings

import { calculateTokenCost } from '@xtnd-dynamics/xtnd-sonar-sdk';

const cost = calculateTokenCost('claude-3-7-sonnet', {
  promptTokens: 12000,
  cachedPromptTokens: 10000, // 10k cached tokens @ $0.30/1M
  completionTokens: 1500,
});

console.log(`Total Cost: $${cost.totalCostUsd.toFixed(4)}`);
console.log(`Cache Savings: $${cost.cacheSavingsUsd.toFixed(4)}`);

4.2 Multi-Account Quota Tracking

import { sonar } from '@xtnd-dynamics/xtnd-sonar-sdk';

// Update current monthly billing state
sonar.quotas.updateQuota({
  provider: 'openai',
  monthlyLimitUsd: 500.00,
  currentSpendUsd: 184.20,
  billingRenewsAt: '2026-09-30T00:00:00Z',
});

// Check remaining headroom
const quota = sonar.quotas.getQuota('openai');
console.log(`Remaining: ${quota?.remainingPercent.toFixed(1)}%`);

// Calculate days/hours until renewal
const renewal = sonar.quotas.calculateTimeUntilRenewal('openai');
console.log(`Renews in: ${renewal.days} days and ${renewal.hours} hours`);