@revenium/claude-code-metering 0.1.4 → 0.1.5

package/src/core/api/client.ts

@@ -0,0 +1,194 @@
+import type {
+  OTLPLogsPayload,
+  OTLPResponse,
+  HealthCheckResult,
+} from "../../types/index.js";
+import { getFullOtlpEndpoint } from "../config/loader.js";
+
+/**
+ * Sends an OTLP logs payload to the Revenium endpoint.
+ */
+export async function sendOtlpLogs(
+  baseEndpoint: string,
+  apiKey: string,
+  payload: OTLPLogsPayload,
+): Promise<OTLPResponse> {
+  const fullEndpoint = getFullOtlpEndpoint(baseEndpoint);
+  const url = `${fullEndpoint}/v1/logs`;
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), 10_000);
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": apiKey,
+    },
+    body: JSON.stringify(payload),
+    signal: controller.signal,
+  }).finally(() => clearTimeout(timeoutId));
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    const safeErrorText =
+      errorText.length > 200 ? errorText.substring(0, 200) + "..." : errorText;
+    throw new Error(
+      `OTLP request failed: ${response.status} ${response.statusText} - ${safeErrorText}`,
+    );
+  }
+
+  return response.json() as Promise<OTLPResponse>;
+}
+
+/**
+ * Options for creating a test payload.
+ */
+export interface TestPayloadOptions {
+  /** Optional subscriber email for attribution */
+  email?: string;
+  /** Optional organization name to attribute costs to */
+  organizationName?: string;
+  /**
+   * @deprecated Use organizationName instead. This field will be removed in a future version.
+   */
+  organizationId?: string;
+  /** Optional product name to attribute costs to */
+  productName?: string;
+  /**
+   * @deprecated Use productName instead. This field will be removed in a future version.
+   */
+  productId?: string;
+}
+
+/**
+ * Creates a minimal test OTLP logs payload.
+ */
+export function createTestPayload(
+  sessionId: string,
+  options?: TestPayloadOptions,
+): OTLPLogsPayload {
+  const now = Date.now() * 1_000_000; // Convert to nanoseconds
+
+  // Build log record attributes
+  // Note: organization.name and product.name go here because ClaudeCodeMapper reads from log record attrs
+  const logAttributes: Array<{ key: string; value: { stringValue: string } }> =
+    [
+      { key: "session.id", value: { stringValue: sessionId } },
+      { key: "model", value: { stringValue: "cli-connectivity-test" } },
+      { key: "input_tokens", value: { stringValue: "0" } },
+      { key: "output_tokens", value: { stringValue: "0" } },
+      { key: "cache_read_tokens", value: { stringValue: "0" } },
+      { key: "cache_creation_tokens", value: { stringValue: "0" } },
+      { key: "cost_usd", value: { stringValue: "0.0" } },
+      { key: "duration_ms", value: { stringValue: "0" } },
+    ];
+
+  // Add optional subscriber/attribution attributes at log record level
+  // (backend ClaudeCodeMapper reads these from log record attrs, not resource attrs)
+  if (options?.email) {
+    logAttributes.push({
+      key: "user.email",
+      value: { stringValue: options.email },
+    });
+  }
+
+  // Support both new (organizationName) and old (organizationId) field names with fallback
+  const organizationValue =
+    options?.organizationName || options?.organizationId;
+  if (organizationValue) {
+    logAttributes.push({
+      key: "organization.name",
+      value: { stringValue: organizationValue },
+    });
+  }
+
+  // Support both new (productName) and old (productId) field names with fallback
+  const productValue = options?.productName || options?.productId;
+  if (productValue) {
+    logAttributes.push({
+      key: "product.name",
+      value: { stringValue: productValue },
+    });
+  }
+
+  // Build resource attributes (only service.name needed here)
+  const resourceAttributes: Array<{
+    key: string;
+    value: { stringValue: string };
+  }> = [{ key: "service.name", value: { stringValue: "claude-code" } }];
+
+  return {
+    resourceLogs: [
+      {
+        resource: {
+          attributes: resourceAttributes,
+        },
+        scopeLogs: [
+          {
+            scope: {
+              name: "claude_code",
+              version: "0.1.0",
+            },
+            logRecords: [
+              {
+                timeUnixNano: now.toString(),
+                body: { stringValue: "claude_code.api_request" },
+                attributes: logAttributes,
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+/**
+ * Generates a unique session ID for test payloads.
+ */
+export function generateTestSessionId(): string {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 8);
+  return `test-${timestamp}-${random}`;
+}
+
+/**
+ * Performs a health check by sending a minimal test payload to the endpoint.
+ */
+export async function checkEndpointHealth(
+  baseEndpoint: string,
+  apiKey: string,
+  options?: TestPayloadOptions,
+): Promise<HealthCheckResult> {
+  const startTime = Date.now();
+
+  try {
+    const sessionId = generateTestSessionId();
+    const payload = createTestPayload(sessionId, options);
+    const response = await sendOtlpLogs(baseEndpoint, apiKey, payload);
+
+    const latencyMs = Date.now() - startTime;
+
+    return {
+      healthy: true,
+      statusCode: 200,
+      message: `Endpoint healthy. Processed ${response.processedEvents} event(s).`,
+      latencyMs,
+    };
+  } catch (error) {
+    const latencyMs = Date.now() - startTime;
+    const message = error instanceof Error ? error.message : "Unknown error";
+
+    // Try to extract status code from error message
+    const statusMatch = message.match(/(\d{3})/);
+    const statusCode = statusMatch ? parseInt(statusMatch[1], 10) : undefined;
+
+    return {
+      healthy: false,
+      statusCode,
+      message,
+      latencyMs,
+    };
+  }
+}

package/src/core/config/loader.ts

@@ -0,0 +1,217 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import {
+  CLAUDE_CONFIG_DIR,
+  REVENIUM_ENV_FILE,
+  ENV_VARS,
+  OTLP_PATH,
+} from "../../utils/constants.js";
+import type { ReveniumConfig } from "../../types/index.js";
+import type { SubscriptionTier } from "../../utils/constants.js";
+
+/**
+ * Gets the path to the Revenium configuration file.
+ */
+export function getConfigPath(): string {
+  return join(homedir(), CLAUDE_CONFIG_DIR, REVENIUM_ENV_FILE);
+}
+
+/**
+ * Checks if the configuration file exists.
+ */
+export function configExists(): boolean {
+  return existsSync(getConfigPath());
+}
+
+/**
+ * Parses an .env file content into key-value pairs.
+ */
+export function parseEnvContent(content: string): Record<string, string> {
+  const result: Record<string, string> = {};
+
+  for (const line of content.split("\n")) {
+    let trimmed = line.trim();
+
+    // Skip empty lines and comments
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+
+    // Handle 'export' prefix
+    if (trimmed.startsWith("export ")) {
+      trimmed = trimmed.substring(7).trim();
+    }
+
+    const equalsIndex = trimmed.indexOf("=");
+    if (equalsIndex === -1) {
+      continue;
+    }
+
+    const key = trimmed.substring(0, equalsIndex).trim();
+    let value = trimmed.substring(equalsIndex + 1).trim();
+
+    // Remove surrounding quotes if present and unescape
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.substring(1, value.length - 1);
+      // Unescape common shell escape sequences
+      value = value
+        .replace(/\\"/g, '"')
+        .replace(/\\'/g, "'")
+        .replace(/\\\$/g, "$")
+        .replace(/\\`/g, "`")
+        .replace(/\\\\/g, "\\");
+    }
+
+    result[key] = value;
+  }
+
+  return result;
+}
+
+/**
+ * Extracts the API key from the OTEL_EXPORTER_OTLP_HEADERS value.
+ * Format: "x-api-key=hak_xxx"
+ */
+function extractApiKeyFromHeaders(headers: string): string | undefined {
+  const match = headers.match(/x-api-key=\s*(hak_[^\s"]+)/);
+  return match?.[1];
+}
+
+/**
+ * Extracts the base endpoint from the full OTLP endpoint URL.
+ * Example: "https://api.revenium.ai/meter/v2/otlp" -> "https://api.revenium.ai"
+ */
+function extractBaseEndpoint(fullEndpoint: string): string {
+  try {
+    const url = new URL(fullEndpoint);
+    // Remove the OTLP path suffix to get the base URL
+    // Handle both old path (/meter/v2/ai/otlp) and new path (/meter/v2/otlp)
+    const path = url.pathname;
+    if (path.includes("/meter/v2/otlp") || path.includes("/meter/v2/ai/otlp")) {
+      url.pathname = "";
+    }
+    return url.origin;
+  } catch {
+    return fullEndpoint;
+  }
+}
+
+/**
+ * Parses OTEL_RESOURCE_ATTRIBUTES value into key-value pairs.
+ * Format: "key1=value1,key2=value2"
+ */
+function parseOtelResourceAttributes(value: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  if (!value || typeof value !== "string") return result;
+
+  const pairs = value.split(",");
+  for (const pair of pairs) {
+    const trimmed = pair.trim();
+    if (!trimmed) continue;
+
+    const equalsIndex = trimmed.indexOf("=");
+    if (equalsIndex === -1) continue;
+
+    const key = trimmed.substring(0, equalsIndex).trim();
+    let attrValue = trimmed.substring(equalsIndex + 1).trim();
+
+    try {
+      attrValue = decodeURIComponent(attrValue);
+    } catch {
+      // If decoding fails, use raw value
+    }
+
+    if (key) result[key] = attrValue;
+  }
+  return result;
+}
+
+/**
+ * Loads the Revenium configuration from the .env file.
+ * Returns null if the file doesn't exist.
+ */
+export async function loadConfig(): Promise<ReveniumConfig | null> {
+  const configPath = getConfigPath();
+
+  if (!existsSync(configPath)) {
+    return null;
+  }
+
+  try {
+    const content = await readFile(configPath, "utf-8");
+    const env = parseEnvContent(content);
+
+    const fullEndpoint = env[ENV_VARS.OTLP_ENDPOINT] || "";
+    const headers = env[ENV_VARS.OTLP_HEADERS] || "";
+    const apiKey = extractApiKeyFromHeaders(headers);
+
+    if (!apiKey) {
+      return null;
+    }
+
+    // Parse cost multiplier override if present
+    const costMultiplierStr = env[ENV_VARS.COST_MULTIPLIER];
+    const costMultiplierOverride = costMultiplierStr
+      ? parseFloat(costMultiplierStr)
+      : undefined;
+
+    // Parse OTEL_RESOURCE_ATTRIBUTES for org/product (primary source)
+    const resourceAttrsStr = env["OTEL_RESOURCE_ATTRIBUTES"] || "";
+    const resourceAttrs = parseOtelResourceAttributes(resourceAttrsStr);
+
+    // Support both .name (preferred) and .id (legacy), with fallback to standalone vars
+    // Priority: organizationName > organizationId > organization.name > organization.id > env var
+    const organizationName =
+      resourceAttrs["organization.name"] ||
+      resourceAttrs["organization.id"] ||
+      env[ENV_VARS.ORGANIZATION_ID];
+
+    const productName =
+      resourceAttrs["product.name"] ||
+      resourceAttrs["product.id"] ||
+      env[ENV_VARS.PRODUCT_ID];
+
+    return {
+      apiKey,
+      endpoint: extractBaseEndpoint(fullEndpoint),
+      email: env[ENV_VARS.SUBSCRIBER_EMAIL],
+      subscriptionTier: env[ENV_VARS.SUBSCRIPTION] as
+        | SubscriptionTier
+        | undefined,
+      costMultiplierOverride:
+        costMultiplierOverride !== undefined && !isNaN(costMultiplierOverride)
+          ? costMultiplierOverride
+          : undefined,
+      organizationName,
+      organizationId: organizationName, // Keep for backward compatibility
+      productName,
+      productId: productName, // Keep for backward compatibility
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Checks if the environment variables are currently loaded in the shell.
+ */
+export function isEnvLoaded(): boolean {
+  return (
+    process.env[ENV_VARS.TELEMETRY_ENABLED] === "1" &&
+    !!process.env[ENV_VARS.OTLP_ENDPOINT]
+  );
+}
+
+/**
+ * Gets the full OTLP endpoint URL from a base URL.
+ */
+export function getFullOtlpEndpoint(baseUrl: string): string {
+  // Remove trailing slash if present
+  const cleanUrl = baseUrl.replace(/\/$/, "");
+  return `${cleanUrl}${OTLP_PATH}`;
+}

package/src/core/config/validator.ts

@@ -0,0 +1,142 @@
+import {
+  API_KEY_PREFIX,
+  SUBSCRIPTION_TIER_CONFIG,
+} from "../../utils/constants.js";
+
+const VALID_TIERS = Object.keys(SUBSCRIPTION_TIER_CONFIG);
+import type { ReveniumConfig, ValidationResult } from "../../types/index.js";
+
+/**
+ * Validates that an API key has the correct format.
+ * Valid format: hak_{tenant}_{random}
+ */
+export function validateApiKey(apiKey: string): ValidationResult {
+  const errors: string[] = [];
+
+  if (!apiKey || apiKey.trim() === "") {
+    errors.push("API key is required");
+    return { valid: false, errors };
+  }
+
+  if (!apiKey.startsWith(API_KEY_PREFIX)) {
+    errors.push(`API key must start with "${API_KEY_PREFIX}"`);
+  }
+
+  // Check for at least two underscores (hak_tenant_random)
+  const parts = apiKey.split("_");
+  if (parts.length < 3) {
+    errors.push("API key format should be: hak_{tenant}_{key}");
+  }
+
+  // Minimum length check
+  if (apiKey.length < 12) {
+    errors.push("API key appears too short");
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Validates an email address format.
+ */
+export function validateEmail(email: string): ValidationResult {
+  const errors: string[] = [];
+
+  if (!email || email.trim() === "") {
+    // Email is optional
+    return { valid: true, errors: [] };
+  }
+
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  if (!emailRegex.test(email)) {
+    errors.push("Invalid email format");
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Validates a subscription tier.
+ */
+export function validateSubscriptionTier(tier: string): ValidationResult {
+  const errors: string[] = [];
+
+  if (!tier || tier.trim() === "") {
+    // Tier is optional
+    return { valid: true, errors: [] };
+  }
+
+  const lowerTier = tier.toLowerCase();
+  if (!VALID_TIERS.includes(lowerTier)) {
+    errors.push(
+      `Invalid subscription tier. Valid options: ${VALID_TIERS.join(", ")}`
+    );
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Validates an endpoint URL and ensures it uses HTTPS.
+ */
+export function validateEndpointUrl(endpoint: string): ValidationResult {
+  const errors: string[] = [];
+
+  if (!endpoint || endpoint.trim() === "") {
+    errors.push("Endpoint URL is required");
+    return { valid: false, errors };
+  }
+
+  try {
+    const url = new URL(endpoint);
+    if (url.protocol !== "https:") {
+      errors.push(
+        "Insecure endpoint: HTTPS is required. Only HTTPS endpoints are allowed."
+      );
+    }
+  } catch {
+    errors.push("Invalid endpoint URL format");
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Validates a complete Revenium configuration.
+ */
+export function validateConfig(
+  config: Partial<ReveniumConfig>
+): ValidationResult {
+  const allErrors: string[] = [];
+
+  const apiKeyResult = validateApiKey(config.apiKey || "");
+  allErrors.push(...apiKeyResult.errors);
+
+  const emailResult = validateEmail(config.email || "");
+  allErrors.push(...emailResult.errors);
+
+  if (config.subscriptionTier) {
+    const tierResult = validateSubscriptionTier(config.subscriptionTier);
+    allErrors.push(...tierResult.errors);
+  }
+
+  const endpointResult = validateEndpointUrl(config.endpoint || "");
+  allErrors.push(...endpointResult.errors);
+
+  return {
+    valid: allErrors.length === 0,
+    errors: allErrors,
+  };
+}