VANTAGE
Documentation

Standalone Chronos SDK (@xtnd-dynamics/xtnd-chronos-sdk)

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

1. Overview

@xtnd-dynamics/xtnd-chronos-sdk is the standalone, zero-dependency client library for human activity telemetry, multi-signal project attribution, and Notion timesheet generation.

It can be integrated into desktop background watchers, CLI tools, Electron apps, or local automation scripts (e.g. scripts reading macOS SQLite databases for Apple Mail, WhatsApp, or Call History).

2. Standalone Storage & Gateway Forwarding

The standalone SDK includes a built-in ChronosStorageManager:

  • Buffers normalized evidence events locally in memory.
  • Synchronizes unbilled/unsynced events in batches to https://api.chronos.vantage.xgi.io/v1/events/evidence.
  • Uses unreferenced timers so Node.js worker and CLI processes can terminate cleanly when idle.

3. Exported API

import {
  chronos,                     // Pre-instantiated global singleton
  ChronosClient,               // Custom client constructor
  ChronosEvidenceCollector,    // Multi-source event normalizer
  ContextualAttributionEngine, // Multi-signal scoring engine
  DurationEstimator,           // 15-minute standard block rounding estimator
  WorkSessionCoalescer,        // Temporal clustering & duplicate filter
  ReconciliationEngine,        // Notion overlap reconciliation
  NotionSyncBridge             // Notion API payload generator
} from '@xtnd-dynamics/xtnd-chronos-sdk';

4. Usage Example

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

const client = new ChronosClient('https://api.chronos.vantage.xgi.io', [
  {
    projectId: 'proj-planorama',
    projectName: 'Planorama',
    identifiers: ['ORD-9821'],
    keywords: ['webordre'],
  },
]);

// Ingest local call event
client.collector.recordPhoneCall({
  callId: 'call-44',
  timestamp: Date.now() - 1800000,
  phoneNumber: '+4512345678',
  contactName: 'Jørgen',
  durationSeconds: 1320, // 22 minutes -> rounds to 30 min (0.5h)
});

// Reconstruct work session
const sessions = client.reconstructSessions();

// Generate Notion draft
const drafts = client.reconcileNotion([]);
console.log(drafts[0].durationHours); // 0.5