@revenium/claude-code-metering 0.1.4 → 0.1.5

package/src/types/index.ts

@@ -0,0 +1,110 @@
+import type { SubscriptionTier } from "../utils/constants.js";
+
+/**
+ * Configuration stored in ~/.claude/revenium.env
+ */
+export interface ReveniumConfig {
+  apiKey: string;
+  endpoint: string;
+  email?: string;
+  subscriptionTier?: SubscriptionTier;
+  /** Optional override for the cost multiplier (overrides tier default) */
+  costMultiplierOverride?: number;
+  /** Optional organization name for attributing costs to a specific customer/company */
+  organizationName?: string;
+  /**
+   * @deprecated Use organizationName instead. This field will be removed in a future version.
+   * Organization or company identifier
+   */
+  organizationId?: string;
+  /** Optional product name for attributing costs to a specific product/project */
+  productName?: string;
+  /**
+   * @deprecated Use productName instead. This field will be removed in a future version.
+   * Product or application identifier
+   */
+  productId?: string;
+}
+
+/**
+ * Result of configuration validation
+ */
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+/**
+ * Result of endpoint health check
+ */
+export interface HealthCheckResult {
+  healthy: boolean;
+  statusCode?: number;
+  message: string;
+  latencyMs?: number;
+}
+
+/**
+ * Shell types supported for profile updates
+ */
+export type ShellType = "bash" | "zsh" | "fish" | "unknown";
+
+/**
+ * Result of shell profile update
+ */
+export interface ShellUpdateResult {
+  success: boolean;
+  shellType: ShellType;
+  profilePath?: string;
+  message: string;
+}
+
+/**
+ * OTLP log payload structure (matching backend expectations)
+ */
+export interface OTLPLogsPayload {
+  resourceLogs: Array<{
+    resource?: {
+      attributes?: Array<{
+        key: string;
+        value: OTLPValue;
+      }>;
+    };
+    scopeLogs: Array<{
+      scope?: {
+        name: string;
+        version: string;
+      };
+      logRecords: Array<{
+        timeUnixNano?: string;
+        body: OTLPValue;
+        attributes: Array<{
+          key: string;
+          value: OTLPValue;
+        }>;
+      }>;
+    }>;
+  }>;
+}
+
+/**
+ * OTLP any value type
+ */
+export interface OTLPValue {
+  stringValue?: string;
+  intValue?: number;
+  doubleValue?: number;
+  boolValue?: boolean;
+}
+
+/**
+ * Response from OTLP endpoint
+ */
+export interface OTLPResponse {
+  id: string;
+  resourceType: string;
+  processedEvents: number;
+  created: string;
+}
+
+export * from "./tool-metering.js";

package/src/types/tool-metering.ts

@@ -0,0 +1,38 @@
+export interface ToolContext {
+  sessionId?: string;
+  userId?: string;
+  organizationName?: string;
+  productName?: string;
+  apiKey?: string;
+  endpoint?: string;
+}
+
+export interface ToolMetadata {
+  description?: string;
+  category?: string;
+  version?: string;
+  tags?: string[];
+  outputFields?: string[];
+  usageMetadata?: Record<string, unknown>;
+}
+
+export interface ToolEventPayload {
+  toolId: string;
+  sessionId: string;
+  startTime: number;
+  endTime: number;
+  durationMs: number;
+  success: boolean;
+  errorMessage?: string;
+  metadata?: ToolMetadata;
+  userId?: string;
+  organizationName?: string;
+  productName?: string;
+}
+
+export interface ToolCallReport {
+  success: boolean;
+  durationMs: number;
+  errorMessage?: string;
+  metadata?: ToolMetadata;
+}

package/src/utils/constants.ts

@@ -0,0 +1,80 @@
+/**
+ * Constants for the Revenium Claude Code Metering CLI
+ */
+
+/** Default Revenium API base URL */
+export const DEFAULT_REVENIUM_URL = 'https://api.revenium.ai';
+
+/** Path appended to base URL for OTLP endpoint */
+export const OTLP_PATH = '/meter/v2/otlp';
+
+/** API key prefix required for valid Revenium API keys */
+export const API_KEY_PREFIX = 'hak_';
+
+/** Directory for Claude Code configuration */
+export const CLAUDE_CONFIG_DIR = '.claude';
+
+/** Filename for Revenium environment configuration */
+export const REVENIUM_ENV_FILE = 'revenium.env';
+
+/** File permissions for config file (owner read/write only) */
+export const CONFIG_FILE_MODE = 0o600;
+
+/** Available subscription tiers with their cost multipliers
+ *
+ * Cost multipliers represent the effective discount vs API pricing.
+ * Values are estimates based on fully consuming monthly token allotments.
+ *
+ * Calculation basis: Max 20x tier ($200 for 20X tokens = $2,500 API equivalent)
+ * establishes $125 per X tokens at API rates. Other tiers calculated proportionally.
+ *
+ * For detailed explanation and manual override instructions, see README.md
+ */
+export const SUBSCRIPTION_TIER_CONFIG = {
+  pro: {
+    name: 'Pro (~$20 USD/month or local equivalent)',
+    multiplier: 0.16, // $20 / $125 API equivalent = 16%
+  },
+  max_5x: {
+    name: 'Max 5x (~$100 USD/month or local equivalent)',
+    multiplier: 0.16, // $100 / $625 API equivalent = 16%
+  },
+  max_20x: {
+    name: 'Max 20x (~$200 USD/month or local equivalent)',
+    multiplier: 0.08, // $200 / $2,500 API equivalent = 8% (baseline from real data)
+  },
+  team_premium: {
+    name: 'Team Premium (~$125 USD/seat or local equivalent)',
+    multiplier: 0.20, // $125 / $625 API equivalent = 20%
+  },
+  enterprise: {
+    name: 'Enterprise (custom)',
+    multiplier: 0.05, // Custom pricing with best discounts
+  },
+  api: {
+    name: 'API (no subscription)',
+    multiplier: 1.0, // Full API pricing
+  },
+} as const;
+
+export const SUBSCRIPTION_TIERS = Object.keys(SUBSCRIPTION_TIER_CONFIG) as ReadonlyArray<keyof typeof SUBSCRIPTION_TIER_CONFIG>;
+
+export type SubscriptionTier = keyof typeof SUBSCRIPTION_TIER_CONFIG;
+
+/** Get the cost multiplier for a given tier */
+export function getCostMultiplier(tier: SubscriptionTier): number {
+  return SUBSCRIPTION_TIER_CONFIG[tier].multiplier;
+}
+
+/** Environment variable names */
+export const ENV_VARS = {
+  TELEMETRY_ENABLED: 'CLAUDE_CODE_ENABLE_TELEMETRY',
+  OTLP_ENDPOINT: 'OTEL_EXPORTER_OTLP_ENDPOINT',
+  OTLP_HEADERS: 'OTEL_EXPORTER_OTLP_HEADERS',
+  OTLP_PROTOCOL: 'OTEL_EXPORTER_OTLP_PROTOCOL',
+  SUBSCRIBER_EMAIL: 'REVENIUM_SUBSCRIBER_EMAIL',
+  SUBSCRIPTION: 'CLAUDE_CODE_SUBSCRIPTION',
+  COST_MULTIPLIER: 'CLAUDE_CODE_COST_MULTIPLIER',
+  ORGANIZATION_ID: 'REVENIUM_ORGANIZATION_ID',
+  PRODUCT_ID: 'REVENIUM_PRODUCT_ID',
+} as const;

package/src/utils/hashing.ts

@@ -0,0 +1,35 @@
+import { createHash } from 'node:crypto';
+
+export interface TransactionIdComponents {
+  sessionId: string;
+  timestamp: string;
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheCreationTokens: number;
+}
+
+/**
+ * Generates a deterministic transaction ID from record components.
+ * Uses SHA-256 hash truncated to 32 hex characters.
+ *
+ * IMPORTANT: This formula must match ClaudeCodeMapper.kt in the backend.
+ * Format: sessionId|timestamp|model|input|output|cacheRead|cacheCreation
+ */
+export function generateTransactionId(components: TransactionIdComponents): string {
+  const input = [
+    components.sessionId,
+    components.timestamp,
+    components.model,
+    components.inputTokens,
+    components.outputTokens,
+    components.cacheReadTokens,
+    components.cacheCreationTokens,
+  ].join('|');
+
+  return createHash('sha256')
+    .update(input)
+    .digest('hex')
+    .substring(0, 32);
+}

package/src/utils/masking.ts

@@ -0,0 +1,32 @@
+/**
+ * Utility functions for masking sensitive data in terminal output
+ */
+
+/**
+ * Masks an API key, showing only the prefix and last 4 characters.
+ * Example: "hak_tenant_abc123xyz" -> "hak_***xyz"
+ */
+export function maskApiKey(apiKey: string): string {
+  if (!apiKey || apiKey.length < 8) {
+    return '***';
+  }
+
+  const prefix = apiKey.substring(0, 4); // "hak_"
+  const lastFour = apiKey.substring(apiKey.length - 4);
+  return `${prefix}***${lastFour}`;
+}
+
+/**
+ * Masks an email address, showing only the first character and domain.
+ * Example: "dev@company.com" -> "d***@company.com"
+ */
+export function maskEmail(email: string): string {
+  const atIndex = email.indexOf('@');
+  if (atIndex <= 0) {
+    return '***';
+  }
+
+  const firstChar = email.charAt(0);
+  const domain = email.substring(atIndex);
+  return `${firstChar}***${domain}`;
+}

package/tests/integration/cli-commands.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { setupCommand } from "../../src/cli/commands/setup.js";
+import { backfillCommand } from "../../src/cli/commands/backfill.js";
+import * as loader from "../../src/core/config/loader.js";
+import * as writer from "../../src/core/config/writer.js";
+import * as client from "../../src/core/api/client.js";
+import * as profileUpdater from "../../src/core/shell/profile-updater.js";
+import * as detector from "../../src/core/shell/detector.js";
+import inquirer from "inquirer";
+import { readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+
+vi.mock("inquirer");
+vi.mock("../../src/core/config/loader.js");
+vi.mock("../../src/core/config/writer.js");
+vi.mock("../../src/core/api/client.js");
+vi.mock("../../src/core/shell/profile-updater.js");
+vi.mock("../../src/core/shell/detector.js");
+vi.mock("node:fs/promises");
+vi.mock("node:fs");
+vi.mock("ora", () => ({
+  default: vi.fn(() => ({
+    start: vi.fn().mockReturnThis(),
+    succeed: vi.fn().mockReturnThis(),
+    fail: vi.fn().mockReturnThis(),
+    warn: vi.fn().mockReturnThis(),
+    text: "",
+  })),
+}));
+
+describe("CLI Commands Integration", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.spyOn(process, "exit").mockImplementation((() => {}) as any);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("setup command end-to-end", () => {
+    it("should complete full setup flow successfully", async () => {
+      vi.mocked(inquirer.prompt).mockResolvedValue({
+        apiKey: "hak_test123",
+        endpoint: "https://api.revenium.ai",
+        email: "test@example.com",
+        tier: "pro",
+      } as any);
+
+      vi.mocked(client.checkEndpointHealth).mockResolvedValue({
+        healthy: true,
+        statusCode: 200,
+        message: "OK",
+        latencyMs: 50,
+      });
+
+      vi.mocked(writer.writeConfig).mockResolvedValue(
+        "/home/user/.claude/revenium.env",
+      );
+
+      vi.mocked(profileUpdater.updateShellProfile).mockResolvedValue({
+        success: true,
+        shellType: "bash",
+        profilePath: "/home/user/.bashrc",
+        message: "Added configuration to /home/user/.bashrc",
+      });
+
+      await setupCommand({});
+
+      expect(inquirer.prompt).toHaveBeenCalled();
+      expect(client.checkEndpointHealth).toHaveBeenCalledWith(
+        "https://api.revenium.ai",
+        "hak_test123",
+      );
+      expect(writer.writeConfig).toHaveBeenCalledWith(
+        expect.objectContaining({
+          apiKey: "hak_test123",
+          endpoint: "https://api.revenium.ai",
+          email: "test@example.com",
+          subscriptionTier: "pro",
+        }),
+      );
+      expect(profileUpdater.updateShellProfile).toHaveBeenCalled();
+    });
+
+    it("should handle health check failure gracefully", async () => {
+      vi.mocked(inquirer.prompt).mockResolvedValue({
+        apiKey: "hak_invalid",
+        endpoint: "https://api.revenium.ai",
+      } as any);
+
+      vi.mocked(client.checkEndpointHealth).mockResolvedValue({
+        healthy: false,
+        statusCode: 401,
+        message: "Unauthorized",
+        latencyMs: 100,
+      });
+
+      await setupCommand({});
+
+      expect(process.exit).toHaveBeenCalledWith(1);
+    });
+
+    it("should skip shell update when option is set", async () => {
+      vi.mocked(inquirer.prompt).mockResolvedValue({
+        apiKey: "hak_test123",
+        endpoint: "https://api.revenium.ai",
+      } as any);
+
+      vi.mocked(client.checkEndpointHealth).mockResolvedValue({
+        healthy: true,
+        statusCode: 200,
+        message: "OK",
+        latencyMs: 50,
+      });
+
+      vi.mocked(writer.writeConfig).mockResolvedValue(
+        "/home/user/.claude/revenium.env",
+      );
+
+      await setupCommand({ skipShellUpdate: true });
+
+      expect(profileUpdater.updateShellProfile).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("backfill command end-to-end", () => {
+    it("should exit when config is not found", async () => {
+      vi.mocked(loader.loadConfig).mockResolvedValue(null);
+      vi.mocked(process.exit).mockImplementation((() => {
+        throw new Error("process.exit called");
+      }) as any);
+
+      await expect(backfillCommand({})).rejects.toThrow("process.exit called");
+
+      expect(console.log).toHaveBeenCalledWith(
+        expect.stringContaining("Configuration not found"),
+      );
+    });
+
+    it("should handle dry-run mode", async () => {
+      vi.mocked(loader.loadConfig).mockResolvedValue({
+        apiKey: "hak_test123",
+        endpoint: "https://api.revenium.ai",
+        subscriptionTier: "pro",
+      });
+
+      vi.mocked(readdir).mockResolvedValue([] as any);
+      vi.mocked(existsSync).mockReturnValue(false);
+
+      await backfillCommand({ dryRun: true });
+
+      expect(client.sendOtlpLogs).not.toHaveBeenCalled();
+    });
+  });
+});