analytics

The analytics extension provides payment tracking, reporting, and export functionality.

Installation

bun add @regent/analytics

Basic Usage

import { createAgent } from '@regent/core';
import { payments } from '@regent/x402';
import { analytics, getSummary, exportToCSV } from '@regent/analytics';

const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
})
  .use(payments({ config: paymentsConfig }))
  .use(analytics())
  .build();

// Get payment summary
const summary = await getSummary(agent.analytics.paymentTracker);

// Export to CSV
const csv = await exportToCSV(agent.analytics.paymentTracker);

API Reference

analytics()

Creates the analytics extension.

function analytics(): Extension<AnalyticsRuntime>

AnalyticsRuntime

type AnalyticsRuntime = {
  readonly paymentTracker: PaymentTracker | undefined;
};

Summary Functions

getSummary()

Get combined summary of all payments.

async function getSummary(
  paymentTracker: PaymentTracker,
  windowMs?: number
): Promise<AnalyticsSummary>

getOutgoingSummary()

Get summary of outgoing payments only.

async function getOutgoingSummary(
  paymentTracker: PaymentTracker,
  windowMs?: number
): Promise<AnalyticsSummary>

getIncomingSummary()

Get summary of incoming payments only.

async function getIncomingSummary(
  paymentTracker: PaymentTracker,
  windowMs?: number
): Promise<AnalyticsSummary>

AnalyticsSummary

type AnalyticsSummary = {
  outgoingTotal: bigint;      // Total outgoing (base units)
  incomingTotal: bigint;      // Total incoming (base units)
  netTotal: bigint;           // Incoming - outgoing
  outgoingCount: number;      // Number of outgoing transactions
  incomingCount: number;      // Number of incoming transactions
  windowStart?: number;       // Query window start
  windowEnd?: number;         // Query window end
};

Transaction Functions

getAllTransactions()

Get all transactions for a time window.

async function getAllTransactions(
  paymentTracker: PaymentTracker,
  windowMs?: number
): Promise<Transaction[]>

getAnalyticsData()

Get complete analytics data with summary and transactions.

async function getAnalyticsData(
  paymentTracker: PaymentTracker,
  windowMs?: number
): Promise<AnalyticsData>

Transaction Type

type Transaction = {
  id?: number;
  groupName: string;
  scope: string;
  direction: 'outgoing' | 'incoming';
  amount: bigint;
  timestamp: number;
  amountUsdc: string;         // Formatted (e.g., "1.5")
  timestampIso: string;       // ISO 8601 format
};

AnalyticsData

type AnalyticsData = {
  summary: AnalyticsSummary;
  transactions: Transaction[];
};

Export Functions

exportToCSV()

Export transactions to CSV format.

async function exportToCSV(
  paymentTracker: PaymentTracker,
  windowMs?: number
): Promise<string>

Features:

• Proper CSV escaping

• Formula injection protection

• Compatible with Excel, Google Sheets, accounting software

CSV Format:

id,groupName,scope,direction,amountUsdc,timestamp,timestampIso
1,trading,global,outgoing,1.5,1702000000000,2023-12-08T10:00:00.000Z

exportToJSON()

Export analytics data to JSON format.

async function exportToJSON(
  paymentTracker: PaymentTracker,
  windowMs?: number
): Promise<string>

Features:

• Pretty-printed output

• BigInt serialization to strings

• Complete summary and transaction data

Time Windows

All functions accept an optional windowMs parameter:

// Last 24 hours
const summary = await getSummary(tracker, 24 * 60 * 60 * 1000);

// Last 7 days
const transactions = await getAllTransactions(tracker, 7 * 24 * 60 * 60 * 1000);

// All time (no window)
const allData = await getAnalyticsData(tracker);

Examples

Daily Revenue Report

const oneDayMs = 24 * 60 * 60 * 1000;
const summary = await getSummary(tracker, oneDayMs);

console.log(`Revenue: ${summary.incomingTotal}`);
console.log(`Expenses: ${summary.outgoingTotal}`);
console.log(`Net: ${summary.netTotal}`);

Monthly Export

import { writeFileSync } from 'fs';

const thirtyDaysMs = 30 * 24 * 60 * 60 * 1000;

const csv = await exportToCSV(tracker, thirtyDaysMs);
writeFileSync('monthly-payments.csv', csv);

const json = await exportToJSON(tracker, thirtyDaysMs);
writeFileSync('monthly-payments.json', json);

Real-time Dashboard

setInterval(async () => {
  const data = await getAnalyticsData(tracker);
  updateDashboard({
    totalIn: data.summary.incomingTotal,
    totalOut: data.summary.outgoingTotal,
    recentTx: data.transactions.slice(0, 10),
  });
}, 60000);

Exports

// Extension
export { analytics } from '@regent/analytics';

// Summary functions
export { getSummary, getOutgoingSummary, getIncomingSummary } from '@regent/analytics';

// Transaction functions
export { getAllTransactions, getAnalyticsData } from '@regent/analytics';

// Export functions
export { exportToCSV, exportToJSON } from '@regent/analytics';

// Types
export type {
  AnalyticsRuntime,
  AnalyticsSummary,
  Transaction,
  AnalyticsData,
} from '@regent/analytics';