npm package: @revenium/google-genai
Description: Transparent TypeScript middleware for automatic Revenium usage tracking with Google AI (Gemini)
Author: Revenium
Latest version: 0.2.3

# Revenium Middleware for Google AI (Node.js)

[![npm version](https://img.shields.io/npm/v/@revenium/google-genai.svg)](https://www.npmjs.com/package/@revenium/google-genai)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org/)
[![Documentation](https://img.shields.io/badge/docs-revenium.io-blue)](https://docs.revenium.io)
[![Website](https://img.shields.io/badge/website-revenium.ai-blue)](https://www.revenium.ai)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Automatically track and meter your Google AI API usage with Revenium. This middleware provides seamless integration with Google AI (Gemini), requiring minimal code changes.

## Features

- **Complete Metering**: Track tokens, costs, and performance metrics
- **Prompt Capture**: Optional capture of prompts and responses with automatic credential sanitization
- **Custom Metadata**: Add business context to your AI usage
- **Streaming Support**: Real-time streaming with analytics
- **Vector Embeddings**: Full embedding support for semantic search
- **Type Safe**: Full TypeScript support with comprehensive types
- **Analytics**: Detailed usage analytics and reporting

## Getting Started

### Quick Start

```bash
npm install @revenium/google-genai
```

For complete setup instructions and usage examples, see the examples linked throughout this guide.

### Step-by-Step Guide

The following guide walks you through setting up Revenium middleware in your project:

### Step 1: Install the Package

```bash
npm install @revenium/google-genai
```

### Step 2: Get Your API Keys

**Revenium API Key:**

1. Go to [Revenium Dashboard](https://app.revenium.ai)
2. Sign up or log in
3. Navigate to API Keys section
4. Copy your API key (starts with `hak_`)

**Google AI API Key:**

1. Go to [Google AI Studio](https://aistudio.google.com/app/apikey)
2. Sign in with your Google account
3. Click "Create API Key"
4. Copy your API key

### Step 3: Setup Environment Variables

Create a `.env` file in your project root:

```bash
# Create .env file
echo. > .env  # On Windows (CMD TERMINAL)
touch .env  # On Mac/Linux (CMD TERMINAL)
# OR
#PowerShell
New-Item -Path .env -ItemType File
```

**Note:** A template `.env.example` file is included in this package at `node_modules/@revenium/google-genai/examples/.env.example` with all required variables and helpful comments.

Copy and paste the following into `.env`:

```env
# Google AI Configuration
GOOGLE_API_KEY=your_google_ai_api_key_here

# Revenium Configuration
REVENIUM_METERING_API_KEY=your_revenium_api_key_here

# Optional: For development/testing (defaults to https://api.revenium.ai)
# REVENIUM_METERING_BASE_URL=https://api.revenium.ai

# Optional: Enable debug logging
REVENIUM_LOG_LEVEL=INFO
```

### Step 4: Implement in Your Code

Create `test-google.js` with basic usage:

```javascript
import { GoogleGenAIController } from "@revenium/google-genai";

const controller = new GoogleGenAIController();
const result = await controller.createChat(
  ["What is artificial intelligence?"],
  "gemini-2.0-flash-001",
);
```

For a complete working example, see: [Google AI Basic Example](https://github.com/revenium/revenium-middleware-google-node/blob/HEAD/packages/google-genai/examples/basic.ts)

Use the examples as reference for implementing the middleware in your project. See the examples linked above for complete implementation including:

- How to initialize the controller
- Making API calls with automatic metering
- Handling streaming responses
- Adding custom metadata to track business context

### Step 5: Update package.json (Optional)

Add test scripts and module type to your `package.json`:

```json
{
  "name": "my-google-ai-project",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "test-google": "node test-google.js"
  },
  "dependencies": {
    "@revenium/google-genai": "^0.1.1"
  }
}
```

**Important:** If you get a "Cannot use import statement outside a module" error, make sure your `package.json` includes `"type": "module"` as shown above.

### Next Steps

For more advanced usage including streaming, embeddings, and custom metadata, see the complete examples:

- [Google AI Basic Example](https://github.com/revenium/revenium-middleware-google-node/blob/HEAD/packages/google-genai/examples/basic.ts)
- [Google AI Streaming Example](https://github.com/revenium/revenium-middleware-google-node/blob/HEAD/packages/google-genai/examples/streaming.ts)
- [Google AI Embedding Example](https://github.com/revenium/revenium-middleware-google-node/blob/HEAD/packages/google-genai/examples/embedding.ts)

---

## Running Examples from Cloned Repository

If you've cloned this repository from GitHub and want to **run the included examples** to see how the middleware works (without modifying the middleware source code):

### Setup

```bash
# Clone the repository
git clone https://github.com/revenium/revenium-middleware-google-node.git
cd revenium-middleware-google-node

# Install dependencies
npm install

# Build the packages
npm run build

# Configure environment variables
cp .env.example .env
# Edit .env with your API keys
```

### Run Examples

**Using npm scripts:**

```bash
# Google AI examples
npm run example:genai:basic      # Basic chat completion
npm run example:genai:streaming  # Streaming response
npm run example:genai:embedding  # Text embeddings
```

**Or use npx tsx directly:**

```bash
npx tsx packages/google-genai/examples/basic.ts
npx tsx packages/google-genai/examples/streaming.ts
npx tsx packages/google-genai/examples/embedding.ts
```

For detailed information about each example, see the examples directory.

### Want to Modify the Middleware Code?

If you're planning to modify the examples or experiment with the code, the setup above is sufficient. However, if you want to **modify the middleware source code itself** (files in `packages/google-genai/src/`), you'll need to understand the development workflow.

See [Local Development and Contributing](#local-development-and-contributing) below for the complete development guide.

---

Already have a project? Just install and replace imports:

### Step 1. Install the Package

```bash
npm install @revenium/google-genai
```

### Step 2. Add Environment Variables

Add to your existing `.env` file:

```env
GOOGLE_API_KEY=your_google_ai_api_key_here
REVENIUM_METERING_API_KEY=your_revenium_api_key_here

# Optional: For development/testing (defaults to https://api.revenium.ai)
# REVENIUM_METERING_BASE_URL=https://api.revenium.ai

# Optional: Enable debug logging
REVENIUM_LOG_LEVEL=INFO
```

### Step 3. Replace Your Imports

**Before:**

```javascript
import { GoogleGenerativeAI } from "@google/generative-ai";
```

**After:**

```javascript
import { GoogleGenAIController } from "@revenium/google-genai";
```

### Step 4. Update Your Code

**Basic usage pattern:**

```javascript
import { GoogleGenAIController } from "@revenium/google-genai";

const controller = new GoogleGenAIController();
const result = await controller.createChat(
  ["Your prompt here"],
  "gemini-2.0-flash-001", // required model parameter
);
```

**For complete working examples, see:**

- [Google AI Basic Example](https://github.com/revenium/revenium-middleware-google-node/blob/HEAD/packages/google-genai/examples/basic.ts) - Chat, streaming, and embeddings
- [Google AI Streaming Example](https://github.com/revenium/revenium-middleware-google-node/blob/HEAD/packages/google-genai/examples/streaming.ts) - Advanced streaming patterns
- [Google AI Embedding Example](https://github.com/revenium/revenium-middleware-google-node/blob/HEAD/packages/google-genai/examples/embedding.ts) - Text embeddings

## Advanced Usage

### Streaming Responses

**Basic streaming pattern:**

```javascript
const result = await controller.createStreaming(
  ["Your prompt here"],
  "gemini-2.0-flash-001",
);

for await (const chunk of result.stream) {
  // Process streaming chunks
}
```

**For complete streaming examples with performance tracking and metadata, see:**

- [Google AI Streaming Example](https://github.com/revenium/revenium-middleware-google-node/blob/HEAD/packages/google-genai/examples/streaming.ts)

### Text Embeddings

**Basic embedding pattern:**

```javascript
const result = await controller.createEmbedding(
  "Text to embed",
  "text-embedding-004",
);
```

**For complete embedding examples with metadata and batch processing, see:**

- [Google AI Embedding Example](https://github.com/revenium/revenium-middleware-google-node/blob/HEAD/packages/google-genai/examples/embedding.ts)

### Custom Metadata Tracking

Add business context to your AI usage. See the [Revenium Metering API Reference](https://revenium.readme.io/reference/meter_ai_completion) for complete header options.

#### Metadata Fields

The `usageMetadata` parameter supports the following fields for detailed tracking:

| Field                      | Description                              | Use Case                       |
| -------------------------- | ---------------------------------------- | ------------------------------ |
| `traceId`                  | Session/conversation tracking identifier | Distributed tracing, debugging |
| `taskType`                 | AI task categorization                   | Cost analysis by workload type |
| `subscriberId`             | User identifier                          | Billing, rate limiting         |
| `subscriberEmail`          | User email address                       | Support, compliance            |
| `subscriberCredentialName` | Auth credential name                     | Track API keys                 |
| `subscriberCredential`     | Auth credential value                    | Security auditing              |
| `organizationId`           | Organization ID                          | Multi-tenant cost allocation   |
| `subscriptionId`           | Subscription plan ID                     | Plan limit tracking            |
| `productId`                | Product/feature ID                       | Feature cost attribution       |
| `agent`                    | AI agent identifier                      | Distinguish workflows          |
| `responseQualityScore`     | Quality rating 0.0-1.0                   | Performance analysis           |
| `modelSource`              | Routing layer (e.g., DIRECT, GOOGLE)     | Integration analytics          |
| `systemFingerprint`        | Provider-issued model fingerprint        | Debugging and attribution      |
| `temperature`              | Sampling temperature applied             | Compare response creativity    |
| `errorReason`              | Upstream error message                   | Error monitoring               |
| `mediationLatency`         | Gateway latency in ms                    | Diagnose mediation overhead    |

> **Note:** The Google middleware accepts these fields in a flat structure. Internally, subscriber fields are transformed to a nested structure (`subscriber.id`, `subscriber.email`, `subscriber.credential.name`, `subscriber.credential.value`) before being sent to the Revenium API.

#### Usage Example

**Basic pattern with metadata:**

```javascript
const customMetadata = {
  subscriberId: "user-123",
  subscriberEmail: "user@example.com",
  organizationId: "org-456",
  productId: "chat-app",
};

const result = await controller.createChat(
  ["Your prompt here"],
  "gemini-2.0-flash-001", // required model parameter
  customMetadata, // optional metadata parameter
);
```

**For complete metadata examples with all available fields, see:**

- [Google AI Basic Example](https://github.com/revenium/revenium-middleware-google-node/blob/HEAD/packages/google-genai/examples/basic.ts)
- [Google AI Streaming Example](https://github.com/revenium/revenium-middleware-google-node/blob/HEAD/packages/google-genai/examples/streaming.ts)
- [Google AI Embedding Example](https://github.com/revenium/revenium-middleware-google-node/blob/HEAD/packages/google-genai/examples/embedding.ts)

### Trace Visualization Fields

The middleware automatically captures trace visualization fields for distributed tracing and analytics:

| Field                 | Type   | Description                                                                     | Environment Variable               |
| --------------------- | ------ | ------------------------------------------------------------------------------- | ---------------------------------- |
| `environment`         | string | Deployment environment (production, staging, development)                       | `REVENIUM_ENVIRONMENT`, `NODE_ENV` |
| `operationType`       | string | Operation classification (CHAT, EMBED, etc.) - automatically detected           | N/A (auto-detected)                |
| `operationSubtype`    | string | Additional detail (function_call, etc.) - automatically detected                | N/A (auto-detected)                |
| `retryNumber`         | number | Retry attempt number (0 for first attempt, 1+ for retries)                      | `REVENIUM_RETRY_NUMBER`            |
| `parentTransactionId` | string | Parent transaction reference for distributed tracing                            | `REVENIUM_PARENT_TRANSACTION_ID`   |
| `transactionName`     | string | Human-friendly operation label                                                  | `REVENIUM_TRANSACTION_NAME`        |
| `region`              | string | Cloud region (us-east-1, etc.) - auto-detected from AWS/Azure/GCP               | `AWS_REGION`, `REVENIUM_REGION`    |
| `credentialAlias`     | string | Human-readable credential name                                                  | `REVENIUM_CREDENTIAL_ALIAS`        |
| `traceType`           | string | Categorical identifier (alphanumeric, hyphens, underscores only, max 128 chars) | `REVENIUM_TRACE_TYPE`              |
| `traceName`           | string | Human-readable label for trace instances (max 256 chars)                        | `REVENIUM_TRACE_NAME`              |

**All trace visualization fields are optional.** The middleware will automatically detect and populate these fields when possible.

#### Example Configuration

```env
REVENIUM_ENVIRONMENT=production
REVENIUM_REGION=us-east-1
REVENIUM_CREDENTIAL_ALIAS=Google AI Production Key
REVENIUM_TRACE_TYPE=customer_support
REVENIUM_TRACE_NAME=Support Ticket #12345
REVENIUM_PARENT_TRANSACTION_ID=parent-txn-123
REVENIUM_TRANSACTION_NAME=Answer Customer Question
REVENIUM_RETRY_NUMBER=0
```

## What Gets Tracked

- **Token Usage**: Input and output tokens for accurate billing
- **Request Duration**: Total time for each API call
- **Model Information**: Which model was used
- **Operation Type**: Chat completion, embedding, streaming
- **Error Tracking**: Failed requests and error details
- **Streaming Metrics**: Time to first token for streaming responses

## Supported Models

**Important**: The model parameter is **required** when calling any controller method. You must specify the model explicitly in your code.

This middleware supports **all models available in Google AI Studio**. The middleware does not maintain a hardcoded list of models, ensuring compatibility with new models as Google releases them.

**For the latest available models, see:**

- [Google AI Gemini Model Reference](https://ai.google.dev/gemini-api/docs/models/gemini)

**Example usage:**

```typescript
// Without metadata (clean, simple)
const result = await controller.createChat(
  ["Your prompt here"],
  "gemini-2.0-flash-001", // required model parameter
);

// With metadata (optional)
const metadata = {
  subscriberId: "user-123",
  subscriberEmail: "user@example.com",
  organizationId: "org-456",
  productId: "product-789",
};

const resultWithMetadata = await controller.createChat(
  ["Your prompt here"],
  "gemini-2.0-flash-001",
  metadata, // optional metadata parameter
);
```

**For complete examples with different models and use cases, see:**

- [Google AI Basic Example](https://github.com/revenium/revenium-middleware-google-node/blob/HEAD/packages/google-genai/examples/basic.ts) - Chat and embeddings with various models
- [Google AI Streaming Example](https://github.com/revenium/revenium-middleware-google-node/blob/HEAD/packages/google-genai/examples/streaming.ts) - Streaming with different configurations

## Configuration Options

### Environment Variables

**Required:**

- `GOOGLE_API_KEY` - Your Google AI API key from [Google AI Studio](https://aistudio.google.com/app/apikey)
- `REVENIUM_METERING_API_KEY` - Your Revenium API key from [Revenium Dashboard](https://app.revenium.ai)

**Optional:**

- `REVENIUM_METERING_BASE_URL` - Revenium API base URL (defaults to `https://api.revenium.ai`, only needed for development/testing)
- `REVENIUM_LOG_LEVEL` - Log level: `DEBUG`, `INFO`, `WARN`, `ERROR` (defaults to `INFO`)
- `REVENIUM_PRINT_SUMMARY` - Print cost/metrics summary to console after each request: `true`, `false`, `"human"`, or `"json"` (defaults to `false`)
- `REVENIUM_TEAM_ID` - Your Revenium team ID (required for cost metrics in summary output)
- `REVENIUM_CAPTURE_PROMPTS` - Capture prompts and responses for analysis: `true` or `false` (defaults to `false`)

### Prompt Capture

The middleware can capture prompts and responses for analysis and debugging. This feature is **disabled by default** for privacy and performance.

#### Configuration

Enable via environment variable:

```bash
REVENIUM_CAPTURE_PROMPTS=true
```

#### Per-Request Control

Override the global setting for individual requests:

```typescript
import { GoogleGenAIController } from "@revenium/google-genai";

const controller = new GoogleGenAIController();
const result = await controller.createChat(
  ["What is artificial intelligence?"],
  "gemini-2.0-flash-001",
  {
    capturePrompts: true,
  },
);
```

#### Security

All captured prompts are automatically sanitized to remove sensitive credentials including:

- API keys (sk-\*, sk-proj-\*, sk-ant-\*, AIzaSy\*)
- Bearer tokens
- Passwords
- Generic tokens and api_key fields

### Manual Configuration

Controllers read configuration from environment variables:

```bash
export GOOGLE_API_KEY="your-api-key"
export REVENIUM_METERING_API_KEY="your-revenium-key"

# Optional: Only for development/testing
# export REVENIUM_METERING_BASE_URL="https://api.revenium.ai"
```

Then instantiate the controller:

```typescript
import { GoogleGenAIController } from "@revenium/google-genai";

const controller = new GoogleGenAIController();
const response = await controller.createChat(
  ["Hello world"],
  "gemini-2.0-flash-001",
);
```

**For complete configuration examples, see:**

- [Google AI Basic Example](https://github.com/revenium/revenium-middleware-google-node/blob/HEAD/packages/google-genai/examples/basic.ts)

## Troubleshooting

### Common Issues

**"Missing API Key" Error**

```bash
export GOOGLE_API_KEY="your-actual-api-key"
echo $GOOGLE_API_KEY  # Verify it's set
```

**"Requests not being tracked"**

```bash
export REVENIUM_METERING_API_KEY="your-actual-revenium-key"
export REVENIUM_LOG_LEVEL="DEBUG"  # Enable debug logging
```

**Module Import Errors**

```json
{
  "type": "module"
}
```

## Requirements

- Node.js 18+
- Google AI API key
- Revenium API key

## Documentation

For detailed documentation, visit [docs.revenium.io](https://docs.revenium.io)

## Contributing

See [CONTRIBUTING.md](https://github.com/revenium/revenium-middleware-google-node/blob/HEAD/CONTRIBUTING.md)

## Code of Conduct

See [CODE_OF_CONDUCT.md](https://github.com/revenium/revenium-middleware-google-node/blob/HEAD/CODE_OF_CONDUCT.md)

## Security

See [SECURITY.md](https://github.com/revenium/revenium-middleware-google-node/blob/HEAD/SECURITY.md)

## License

This project is licensed under the MIT License - see the [LICENSE](https://github.com/revenium/revenium-middleware-google-node/blob/HEAD/packages/google-genai/LICENSE) file for details.

## Support

For issues, feature requests, or contributions:

- **GitHub Repository**: [revenium/revenium-middleware-google-node](https://github.com/revenium/revenium-middleware-google-node)
- **Issues**: [Report bugs or request features](https://github.com/revenium/revenium-middleware-google-node/issues)
- **Documentation**: [docs.revenium.io](https://docs.revenium.io)
- **Contact**: Reach out to the Revenium team for additional support

## Local Development and Contributing

**Are you planning to modify the middleware source code?** (Not just run examples)

If you want to:

- Fix bugs in the middleware
- Add new features to @revenium/google-genai
- Contribute to the project
- Test changes to the middleware before publishing

Then follow the complete development workflow in [DEVELOPMENT.md](https://github.com/revenium/revenium-middleware-google-node/blob/HEAD/DEVELOPMENT.md), which covers:

### What DEVELOPMENT.md Includes:

- **Development Workflow** - Step-by-step process for making changes
- **Build System** - Understanding the monorepo and TypeScript compilation
- **Testing Local Changes** - How to test your modifications properly
- **When to Rebuild** - Understanding when `npm run build` is needed
- **Publishing Checklist** - Steps to publish new versions
- **Architecture Notes** - Understanding the codebase structure
- **Contributing Guidelines** - How to contribute to the project

### Key Difference:

- **Running Examples** (above): You can modify example files and run them directly with `npx tsx` - no rebuild needed
- **Modifying Middleware** (DEVELOPMENT.md): If you modify source files in `packages/google-genai/src/`, you must run `npm run build` before testing

**Quick Start for Contributors:**

```bash
# 1. Make changes to source code
vim packages/google-genai/src/googleGenAI.service.ts

# 2. Rebuild the package
npm run build

# 3. Test your changes
npm run example:genai:getting-started

# 4. See DEVELOPMENT.md for complete workflow
```

---

**Built by Revenium**