@revenium/claude-code-metering 0.1.3 → 0.1.5

package/src/core/config/writer.ts

@@ -0,0 +1,212 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { writeFile, mkdir, chmod } from "node:fs/promises";
+import {
+  CLAUDE_CONFIG_DIR,
+  REVENIUM_ENV_FILE,
+  CONFIG_FILE_MODE,
+  ENV_VARS,
+  getCostMultiplier,
+  type SubscriptionTier,
+} from "../../utils/constants.js";
+import type { ReveniumConfig } from "../../types/index.js";
+import { getFullOtlpEndpoint } from "./loader.js";
+
+/**
+ * Escapes a value for use in shell export statements.
+ * Wraps the value in double quotes and escapes special characters.
+ */
+function escapeShellValue(value: string): string {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\$/g, "\\$").replace(/`/g, "\\`")}"`;
+}
+
+/**
+ * Escapes a value for use in OTEL_RESOURCE_ATTRIBUTES.
+ * OTEL_RESOURCE_ATTRIBUTES uses comma as delimiter and equals as key-value separator.
+ * Characters that need escaping: comma (,), equals (=), and double-quote (").
+ * We URL-encode these characters to ensure safe parsing.
+ */
+function escapeResourceAttributeValue(value: string): string {
+  return value
+    .replace(/%/g, "%25") // Escape % first to avoid double-encoding
+    .replace(/,/g, "%2C")
+    .replace(/=/g, "%3D")
+    .replace(/"/g, "%22");
+}
+
+/**
+ * Gets the path to the Claude config directory.
+ */
+function getClaudeConfigDir(): string {
+  return join(homedir(), CLAUDE_CONFIG_DIR);
+}
+
+/**
+ * Generates the content for the revenium.env file.
+ */
+function generateEnvContent(config: ReveniumConfig): string {
+  const fullEndpoint = getFullOtlpEndpoint(config.endpoint);
+
+  const lines: string[] = [
+    "# Revenium Claude Code Metering Configuration",
+    "# Generated by @revenium/claude-code-metering",
+    "#",
+    "# To load these variables, add to your shell profile:",
+    "#   source ~/.claude/revenium.env",
+    "",
+    "# Enable Claude Code telemetry export",
+    `export ${ENV_VARS.TELEMETRY_ENABLED}=1`,
+    "",
+    "# OTLP endpoint for Revenium metering",
+    `export ${ENV_VARS.OTLP_ENDPOINT}=${escapeShellValue(fullEndpoint)}`,
+    "",
+    "# Authentication header with API key",
+    `export ${ENV_VARS.OTLP_HEADERS}=${escapeShellValue(`x-api-key=${config.apiKey}`)}`,
+    "",
+    "# OTLP protocol (required for Claude Code)",
+    `export ${ENV_VARS.OTLP_PROTOCOL}=http/json`,
+    "",
+    "# Enable OTLP logs exporter (required to send telemetry)",
+    "export OTEL_LOGS_EXPORTER=otlp",
+  ];
+
+  // Add optional fields
+  if (config.email) {
+    lines.push("");
+    lines.push("# Subscriber email for attribution");
+    lines.push(
+      `export ${ENV_VARS.SUBSCRIBER_EMAIL}=${escapeShellValue(config.email)}`,
+    );
+  }
+
+  if (config.subscriptionTier) {
+    const tier = config.subscriptionTier as SubscriptionTier;
+    const costMultiplier =
+      config.costMultiplierOverride ?? getCostMultiplier(tier);
+    const discountPercent = Math.round((1 - costMultiplier) * 100);
+
+    lines.push("");
+    lines.push("# Claude Code subscription tier");
+    lines.push(
+      `export ${ENV_VARS.SUBSCRIPTION}=${escapeShellValue(config.subscriptionTier)}`,
+    );
+
+    lines.push("");
+    lines.push("# Cost multiplier for subscription tier");
+    lines.push(
+      "# This adjusts Claude Code costs based on your subscription discount",
+    );
+    lines.push(`# ${tier}: ${discountPercent}% discount vs API rates`);
+    if (config.costMultiplierOverride !== undefined) {
+      lines.push("# (custom override applied)");
+      lines.push(`export ${ENV_VARS.COST_MULTIPLIER}=${costMultiplier}`);
+    }
+    // Build OTEL_RESOURCE_ATTRIBUTES with cost_multiplier and optional organization.name/product.name.
+    // Special characters (,=") in values are URL-encoded to ensure safe parsing.
+    // Note: The backend ONLY reads organization.name and product.name from resourceAttributes,
+    // ignoring any auto-generated values in log record attributes from Claude Code.
+    const resourceAttrs: string[] = [`cost_multiplier=${costMultiplier}`];
+
+    // Support both new (organizationName) and old (organizationId) field names with fallback
+    const organizationValue = config.organizationName || config.organizationId;
+    if (organizationValue) {
+      resourceAttrs.push(
+        `organization.name=${escapeResourceAttributeValue(organizationValue)}`,
+      );
+    }
+
+    // Support both new (productName) and old (productId) field names with fallback
+    const productValue = config.productName || config.productId;
+    if (productValue) {
+      resourceAttrs.push(
+        `product.name=${escapeResourceAttributeValue(productValue)}`,
+      );
+    }
+    lines.push(`export OTEL_RESOURCE_ATTRIBUTES="${resourceAttrs.join(",")}"`);
+  }
+
+  // Add advanced configuration section
+  lines.push("");
+  lines.push(
+    "# ─────────────────────────────────────────────────────────────────────────────",
+  );
+  lines.push("# Organization & Product Attribution (Optional)");
+  lines.push(
+    "# ─────────────────────────────────────────────────────────────────────────────",
+  );
+  lines.push("#");
+  lines.push(
+    "# To attribute Claude Code costs to a specific organization or product, you must",
+  );
+  lines.push(
+    "# add them to OTEL_RESOURCE_ATTRIBUTES above. The backend ONLY reads these values",
+  );
+  lines.push(
+    "# from OTEL_RESOURCE_ATTRIBUTES - standalone environment variables are NOT sent.",
+  );
+  lines.push("#");
+  lines.push("# HOW TO CONFIGURE:");
+  lines.push(
+    "# Edit the OTEL_RESOURCE_ATTRIBUTES line above to include organization.name and/or product.name:",
+  );
+  lines.push("#");
+
+  // Get current cost multiplier for the example
+  const exampleMultiplier =
+    config.subscriptionTier && config.costMultiplierOverride === undefined
+      ? getCostMultiplier(config.subscriptionTier as SubscriptionTier)
+      : (config.costMultiplierOverride ?? "0.08");
+  lines.push(
+    `#   OTEL_RESOURCE_ATTRIBUTES="cost_multiplier=${exampleMultiplier},organization.name=my-org,product.name=my-product"`,
+  );
+  lines.push("#");
+  lines.push("# ATTRIBUTE DESCRIPTIONS:");
+  lines.push(
+    "#   organization.name - Attribute costs to a customer/company (e.g., client name, team)",
+  );
+  lines.push(
+    "#   product.name      - Attribute costs to a product/project (e.g., mobile-app, backend-api)",
+  );
+  lines.push("#");
+  lines.push(
+    "# After editing, restart your terminal or run: source ~/.claude/revenium.env",
+  );
+  lines.push("#");
+  lines.push(
+    "# Alternatively, re-run setup with --organization and --product flags:",
+  );
+  lines.push(
+    "#   npx @revenium/claude-code-metering setup --organization my-org --product my-product",
+  );
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Writes the Revenium configuration to ~/.claude/revenium.env.
+ * Creates the directory if it doesn't exist and sets file permissions to 600.
+ */
+export async function writeConfig(config: ReveniumConfig): Promise<string> {
+  const configDir = getClaudeConfigDir();
+  const configPath = join(configDir, REVENIUM_ENV_FILE);
+
+  // Ensure the directory exists
+  await mkdir(configDir, { recursive: true });
+
+  // Generate and write the content
+  const content = generateEnvContent(config);
+  await writeFile(configPath, content, { encoding: "utf-8" });
+
+  // Set restrictive permissions (owner read/write only)
+  await chmod(configPath, CONFIG_FILE_MODE);
+
+  return configPath;
+}
+
+/**
+ * Gets the path where the config file would be written.
+ */
+export function getConfigFilePath(): string {
+  return join(getClaudeConfigDir(), REVENIUM_ENV_FILE);
+}

package/src/core/shell/detector.ts

@@ -0,0 +1,92 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import type { ShellType } from "../../types/index.js";
+
+/**
+ * Detects the current shell type based on environment variables.
+ */
+export function detectShell(): ShellType {
+  const shell = process.env.SHELL || "";
+
+  if (shell.includes("zsh")) {
+    return "zsh";
+  }
+  if (shell.includes("fish")) {
+    return "fish";
+  }
+  if (shell.includes("bash")) {
+    return "bash";
+  }
+
+  // Fallback: check for rc files
+  const home = homedir();
+  if (existsSync(join(home, ".zshrc"))) {
+    return "zsh";
+  }
+  if (existsSync(join(home, ".config", "fish", "config.fish"))) {
+    return "fish";
+  }
+  if (existsSync(join(home, ".bashrc"))) {
+    return "bash";
+  }
+
+  return "unknown";
+}
+
+/**
+ * Gets the profile file path for a given shell type.
+ */
+export function getProfilePath(shellType: ShellType): string | null {
+  const home = homedir();
+
+  switch (shellType) {
+    case "zsh":
+      return join(home, ".zshrc");
+    case "bash":
+      // Prefer .bashrc, fallback to .bash_profile
+      if (existsSync(join(home, ".bashrc"))) {
+        return join(home, ".bashrc");
+      }
+      return join(home, ".bash_profile");
+    case "fish":
+      return join(home, ".config", "fish", "config.fish");
+    default:
+      return null;
+  }
+}
+
+/**
+ * Validates that a config path contains only safe characters.
+ * Throws an error if the path contains potentially dangerous characters.
+ * Allows spaces since paths are properly quoted in shell commands.
+ */
+export function validateConfigPath(path: string): void {
+  const unsafeCharsRegex = /[;|&$`"'\\<>(){}[\]!*?#\n\r\t]/;
+
+  if (unsafeCharsRegex.test(path)) {
+    throw new Error(
+      `Invalid config path: contains unsafe characters. Path must not contain shell metacharacters like semicolons, pipes, backticks, or quotes.`
+    );
+  }
+}
+
+/**
+ * Generates the source command for a given shell type.
+ * Validates the config path before generating the command.
+ */
+export function getSourceCommand(
+  shellType: ShellType,
+  configPath: string
+): string {
+  validateConfigPath(configPath);
+
+  switch (shellType) {
+    case "fish":
+      // Fish uses a different syntax for sourcing env files
+      return `# Source Revenium Claude Code metering config\nif test -f "${configPath}"\n    export (cat "${configPath}" | grep -v '^#' | xargs -L 1)\nend`;
+    default:
+      // Bash and Zsh use the same syntax
+      return `# Source Revenium Claude Code metering config\nif [ -f "${configPath}" ]; then\n    source "${configPath}"\nfi`;
+  }
+}

package/src/core/shell/profile-updater.ts

@@ -0,0 +1,131 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import type { ShellType, ShellUpdateResult } from "../../types/index.js";
+import { detectShell, getProfilePath, getSourceCommand } from "./detector.js";
+import { getConfigFilePath } from "../config/writer.js";
+
+/** Marker comment to identify our configuration block */
+const CONFIG_MARKER_START = "# >>> revenium-claude-code-metering >>>";
+const CONFIG_MARKER_END = "# <<< revenium-claude-code-metering <<<";
+
+/**
+ * Checks if the shell profile already has the Revenium source command.
+ */
+async function hasReveniumConfig(profilePath: string): Promise<boolean> {
+  if (!existsSync(profilePath)) {
+    return false;
+  }
+
+  const content = await readFile(profilePath, "utf-8");
+  return content.includes(CONFIG_MARKER_START);
+}
+
+/**
+ * Generates the complete configuration block for the shell profile.
+ */
+function generateConfigBlock(shellType: ShellType, configPath: string): string {
+  const sourceCmd = getSourceCommand(shellType, configPath);
+  return `\n${CONFIG_MARKER_START}\n${sourceCmd}\n${CONFIG_MARKER_END}\n`;
+}
+
+/**
+ * Removes existing Revenium configuration from profile content.
+ */
+function removeExistingConfig(content: string): string {
+  const startIndex = content.indexOf(CONFIG_MARKER_START);
+  const endIndex = content.indexOf(CONFIG_MARKER_END);
+
+  if (startIndex === -1 || endIndex === -1) {
+    return content;
+  }
+
+  const before = content.substring(0, startIndex).trimEnd();
+  const after = content
+    .substring(endIndex + CONFIG_MARKER_END.length)
+    .trimStart();
+
+  return before + (after ? "\n" + after : "");
+}
+
+/**
+ * Updates the shell profile to source the Revenium configuration file.
+ * Returns details about the update operation.
+ */
+export async function updateShellProfile(): Promise<ShellUpdateResult> {
+  const shellType = detectShell();
+
+  if (shellType === "unknown") {
+    return {
+      success: false,
+      shellType,
+      message:
+        "Could not detect shell type. Please manually add the source command to your shell profile.",
+    };
+  }
+
+  const profilePath = getProfilePath(shellType);
+
+  if (!profilePath) {
+    return {
+      success: false,
+      shellType,
+      message: `Could not determine profile path for ${shellType}.`,
+    };
+  }
+
+  const configPath = getConfigFilePath();
+
+  try {
+    // Check if already configured
+    if (await hasReveniumConfig(profilePath)) {
+      // Remove existing and re-add (in case config path changed)
+      let content = await readFile(profilePath, "utf-8");
+      content = removeExistingConfig(content);
+      const configBlock = generateConfigBlock(shellType, configPath);
+      await writeFile(profilePath, content + configBlock, "utf-8");
+
+      return {
+        success: true,
+        shellType,
+        profilePath,
+        message: `Updated existing configuration in ${profilePath}`,
+      };
+    }
+
+    // Add new configuration
+    let content = "";
+    if (existsSync(profilePath)) {
+      content = await readFile(profilePath, "utf-8");
+    }
+
+    const configBlock = generateConfigBlock(shellType, configPath);
+    await writeFile(profilePath, content + configBlock, "utf-8");
+
+    return {
+      success: true,
+      shellType,
+      profilePath,
+      message: `Added configuration to ${profilePath}`,
+    };
+  } catch (error) {
+    const errorMessage =
+      error instanceof Error ? error.message : "Unknown error";
+    return {
+      success: false,
+      shellType,
+      profilePath,
+      message: `Failed to update shell profile: ${errorMessage}`,
+    };
+  }
+}
+
+/**
+ * Gets instructions for manual shell profile configuration.
+ */
+export function getManualInstructions(shellType: ShellType): string {
+  const configPath = getConfigFilePath();
+  const sourceCmd = getSourceCommand(shellType, configPath);
+  const profilePath = getProfilePath(shellType);
+
+  return `Add the following to ${profilePath || "your shell profile"}:\n\n${sourceCmd}`;
+}

package/src/core/tool-context.ts

@@ -0,0 +1,23 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { ToolContext } from "../types/tool-metering.js";
+
+const toolContextStorage = new AsyncLocalStorage<ToolContext>();
+
+export function setToolContext(context: ToolContext): void {
+  toolContextStorage.enterWith(context);
+}
+
+export function getToolContext(): ToolContext {
+  return toolContextStorage.getStore() ?? {};
+}
+
+export function clearToolContext(): void {
+  toolContextStorage.enterWith({});
+}
+
+export function runWithToolContext<T>(
+  context: ToolContext,
+  fn: () => T,
+): T {
+  return toolContextStorage.run(context, fn);
+}

package/src/core/tool-tracker.ts

@@ -0,0 +1,204 @@
+import type {
+  ToolMetadata,
+  ToolEventPayload,
+  ToolCallReport,
+} from "../types/tool-metering.js";
+import type { OTLPLogsPayload } from "../types/index.js";
+import { getToolContext } from "./tool-context.js";
+import { sendOtlpLogs } from "./api/client.js";
+import { loadConfig } from "./config/loader.js";
+
+const MIDDLEWARE_SOURCE = "revenium-claude-code-sdk";
+
+function isPromise<T>(value: unknown): value is Promise<T> {
+  return value !== null && typeof value === "object" && typeof (value as Promise<T>).then === "function";
+}
+
+function extractOutputFields(result: unknown, fields: string[]): Record<string, unknown> {
+  if (typeof result !== "object" || result === null) {
+    return {};
+  }
+
+  const extracted: Record<string, unknown> = {};
+  for (const field of fields) {
+    if (field in result) {
+      extracted[field] = (result as Record<string, unknown>)[field];
+    }
+  }
+  return extracted;
+}
+
+function buildToolEventPayload(
+  toolId: string,
+  durationMs: number,
+  success: boolean,
+  errorMessage?: string,
+  metadata?: ToolMetadata,
+): ToolEventPayload {
+  const context = getToolContext();
+  const now = Date.now();
+  return {
+    toolId,
+    sessionId: context?.sessionId ?? "unknown",
+    startTime: now - durationMs,
+    endTime: now,
+    durationMs,
+    success,
+    errorMessage,
+    metadata,
+    userId: context?.userId,
+    organizationName: context?.organizationName,
+    productName: context?.productName,
+  };
+}
+
+function createToolOtlpPayload(event: ToolEventPayload): OTLPLogsPayload {
+  const logAttributes: Array<{ key: string; value: { stringValue?: string; intValue?: number; boolValue?: boolean } }> = [
+    { key: "tool.id", value: { stringValue: event.toolId } },
+    { key: "session.id", value: { stringValue: event.sessionId } },
+    { key: "duration_ms", value: { intValue: event.durationMs } },
+    { key: "success", value: { boolValue: event.success } },
+    { key: "middleware.source", value: { stringValue: MIDDLEWARE_SOURCE } },
+  ];
+
+  if (event.errorMessage) {
+    logAttributes.push({ key: "error.message", value: { stringValue: event.errorMessage } });
+  }
+
+  if (event.userId) {
+    logAttributes.push({ key: "user.id", value: { stringValue: event.userId } });
+  }
+
+  if (event.organizationName) {
+    logAttributes.push({ key: "organization.name", value: { stringValue: event.organizationName } });
+  }
+
+  if (event.productName) {
+    logAttributes.push({ key: "product.name", value: { stringValue: event.productName } });
+  }
+
+  if (event.metadata?.description) {
+    logAttributes.push({ key: "tool.description", value: { stringValue: event.metadata.description } });
+  }
+
+  if (event.metadata?.category) {
+    logAttributes.push({ key: "tool.category", value: { stringValue: event.metadata.category } });
+  }
+
+  if (event.metadata?.version) {
+    logAttributes.push({ key: "tool.version", value: { stringValue: event.metadata.version } });
+  }
+
+  if (event.metadata?.tags && event.metadata.tags.length > 0) {
+    logAttributes.push({ key: "tool.tags", value: { stringValue: event.metadata.tags.join(",") } });
+  }
+
+  return {
+    resourceLogs: [
+      {
+        resource: {
+          attributes: [
+            { key: "service.name", value: { stringValue: "claude-code" } },
+            { key: "middleware.source", value: { stringValue: MIDDLEWARE_SOURCE } },
+          ],
+        },
+        scopeLogs: [
+          {
+            scope: {
+              name: "tool_metering",
+              version: "0.1.0",
+            },
+            logRecords: [
+              {
+                timeUnixNano: (event.endTime * 1_000_000).toString(),
+                body: { stringValue: "tool.call" },
+                attributes: logAttributes,
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+async function sendToolEvent(event: ToolEventPayload): Promise<void> {
+  const context = getToolContext();
+  const config = await loadConfig();
+
+  const endpoint = context?.endpoint ?? config?.endpoint;
+  const apiKey = context?.apiKey ?? config?.apiKey;
+
+  if (!endpoint || !apiKey) {
+    return;
+  }
+
+  const payload = createToolOtlpPayload(event);
+  await sendOtlpLogs(endpoint, apiKey, payload);
+}
+
+function dispatchToolEvent(event: ToolEventPayload): void {
+  sendToolEvent(event).catch(() => {});
+}
+
+export function meterTool<T>(
+  toolId: string,
+  fn: () => T | Promise<T>,
+  metadata?: ToolMetadata,
+): Promise<T> {
+  const startTime = performance.now();
+
+  const handleSuccess = (result: T): T => {
+    const durationMs = Math.round(performance.now() - startTime);
+
+    let finalMetadata = metadata;
+    if (metadata?.outputFields && metadata.outputFields.length > 0) {
+      const extracted = extractOutputFields(result, metadata.outputFields);
+      finalMetadata = {
+        ...metadata,
+        usageMetadata: {
+          ...metadata.usageMetadata,
+          ...extracted,
+        },
+      };
+    }
+
+    const event = buildToolEventPayload(toolId, durationMs, true, undefined, finalMetadata);
+    dispatchToolEvent(event);
+    return result;
+  };
+
+  const handleError = (error: unknown): never => {
+    const durationMs = Math.round(performance.now() - startTime);
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const event = buildToolEventPayload(toolId, durationMs, false, errorMessage, metadata);
+    dispatchToolEvent(event);
+    throw error;
+  };
+
+  try {
+    const result = fn();
+
+    if (isPromise<T>(result)) {
+      return result.then(handleSuccess, handleError);
+    }
+
+    return Promise.resolve(handleSuccess(result));
+  } catch (error) {
+    return Promise.reject(handleError(error));
+  }
+}
+
+export function reportToolCall(
+  toolId: string,
+  report: ToolCallReport,
+): void {
+  const event = buildToolEventPayload(
+    toolId,
+    report.durationMs,
+    report.success,
+    report.errorMessage,
+    report.metadata,
+  );
+  dispatchToolEvent(event);
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+// Re-export types and utilities for programmatic use
+export * from './types/index.js';
+export * from './utils/constants.js';
+export * from './utils/hashing.js';
+export * from './utils/masking.js';
+export * from './core/config/loader.js';
+export * from './core/config/writer.js';
+export * from './core/config/validator.js';
+export * from './core/api/client.js';
+export * from './core/shell/detector.js';
+export * from './core/tool-context.js';
+export * from './core/tool-tracker.js';