@revmax/agent-sdk v0.0.7-beta.1

@revmax/agent-sdk

Official Node.js SDK for the RevMax API. Simplify integration with RevMax's billing, customer management, and usage tracking services.

Installation

npm install @revmax/agent-sdk
# or
yarn add @revmax/agent-sdk

Quick Start

import { RevMaxClient } from '@revmax/agent-sdk';

// Create and connect to the API
const client = new RevMaxClient('revx_pk_your_api_key');
await client.connect();

// Track an event
await client.trackEvent({
  agentId: 'agent_123',
  customerExternalId: 'customer_456',
  signalName: 'lead_generated',
  quantity: 1,
  metadata: {
    eventId: 'lead_generated',
    usageCost: [
      {
        serviceName: 'wfloengine', // Service name
        units: 1, // Units consumed
      },
      {
        serviceName: 'gpt-4o', // Service name
        units: 23471, // Units consumed
      },
    ],
  },
});

Documentation

• Configuration Options
• Event Tracking Examples
• Usage Cost Tracking
• Customer Management
• Error Handling
• Advanced Features
• API Reference

Configuration

const client = new RevMaxClient('revx_pk_your_api_key', {
  baseURL: 'https://api.custom-domain.com/v1',
  timeout: 10000,
  retries: 3,
  retryDelay: 300,
  logging: {
    enabled: true,
    level: 'info',
  },
  telemetry: {
    enabled: true,
    sampleRate: 1,
  },
});

await client.connect();

Usage Examples

Event Tracking

// Simple event tracking
await client.trackEvent({
  agentId: 'agent_123',
  customerExternalId: 'customer_456',
  signalName: 'api_call',
  quantity: 1,
});

// Event with metadata and usage cost tracking
await client.trackEvent({
  agentId: 'agent_123',
  customerExternalId: 'customer_456',
  signalName: 'email_sent',
  quantity: 1,
  metadata: {
    eventId: 'email_sent',
    usageCost: [
      {
        serviceName: 'LLM',
        units: 7,
      },
      {
        serviceName: 'Intuit',
        units: 1,
      },
    ],
  },
});

// Batch tracking
await client.trackEvent({
  records: [
    {
      customerExternalId: 'customer_456',
      agentId: 'agent_123',
      signalName: 'api_call',
      quantity: 10,
      metadata: {
        endpoint: '/api/v1/search',
      },
    },
    {
      customerExternalId: 'customer_789',
      agentId: 'agent_123',
      signalName: 'storage',
      quantity: 100,
      usageDate: new Date('2023-08-15'),
      metadata: {
        storageType: 'object',
      },
    },
  ],
});

Usage Cost Tracking

Track detailed cost breakdown through the usageCost field in metadata:

await client.trackEvent({
  agentId: 'agent_123',
  customerExternalId: 'customer_456',
  signalName: 'lead_generated',
  quantity: 1,
  metadata: {
    eventId: 'lead_generated',
    usageCost: [
      {
        serviceName: 'wfloengine', // Service name
        units: 1, // Units consumed
      },
    ],
  },
});

The usageCost field structure:

Customer Management

// Create a customer
const customer = await client.customers.create({
  name: 'Acme Corp',
  email: 'billing@acmecorp.com',
  externalId: 'acme-123',
});

// List customers
const customers = await client.customers.list({
  limit: 10,
  page: 1,
});

// Get, update and delete customers
const customer = await client.customers.get('customer_id');
await client.customers.update('customer_id', { name: 'Updated Name' });
await client.customers.delete('customer_id');

Error Handling

import {
  RevMaxClient,
  RevMaxApiError,
  RevMaxAuthenticationError,
  RevMaxRateLimitError,
  RevMaxValidationError,
} from '@revmax/agent-sdk';

try {
  await client.connect();
  await client.trackEvent({
    /* ... */
  });
} catch (error) {
  if (error instanceof RevMaxAuthenticationError) {
    console.error(`Authentication failed. Request ID: ${error.requestId}`);
  } else if (error instanceof RevMaxRateLimitError) {
    console.error(`Rate limit exceeded. Retry after ${error.retryAfter}s`);
  } else if (error instanceof RevMaxValidationError) {
    console.error(`Validation error: ${error.message}`);
  } else if (error instanceof RevMaxApiError) {
    console.error(`API Error (${error.statusCode}): ${error.message}`);
  }
}

Advanced Features

Request Retries

const client = new RevMaxClient('revx_pk_your_api_key', {
  retries: 3,
  retryDelay: 300,
});

Logging & Telemetry

The SDK includes a telemetry system that tracks API request performance and usage patterns:

const client = new RevMaxClient('revx_pk_your_api_key', {
  logging: {
    enabled: true,
    level: 'debug',
    handler: (level, message, data) => {
      myLoggingSystem.log(level, message, data);
    },
  },
  telemetry: {
    enabled: true,
    sampleRate: 0.5, // Track 50% of requests
    handler: (metrics) => {
      myMonitoringSystem.trackApiRequest(metrics);
    },
  },
});

You can access telemetry statistics programmatically:

// Get current statistics
const stats = client.getTelemetryStats();
console.log(`Total Requests: ${stats.requestCount}`);
console.log(`Success Rate: ${(stats.successRate * 100).toFixed(2)}%`);

For detailed telemetry configuration including integration with monitoring systems, see Telemetry Documentation.

API Reference

Complete documentation available at docs.userevmax.com.

License

MIT License. See LICENSE for details.