main

Adaline Gateway Repository - Main Rules

Repository Overview

This is a TypeScript-based AI gateway service that provides unified interfaces for multiple AI providers (OpenAI, Anthropic, Google, etc.) with features like caching, queuing, analytics, and telemetry.

Core Architecture Principles

1. Type Safety & Schema Validation

Rules

• ALWAYS use Zod schemas for runtime validation
• ALWAYS export both the schema and inferred types
• NEVER use any type - use proper generic constraints
• ALWAYS validate input/output at runtime using schemas

Instructions

// ✅ CORRECT: Define schema first, then type
import { z } from 'zod';

const UserConfig = z.object({
  apiKey: z.string().min(1),
  model: z.string().min(1),
  temperature: z.number().min(0).max(2).default(1.0),
});
type UserConfigType = z.infer<typeof UserConfig>;

// Export both schema and type
export { UserConfig, type UserConfigType };

// ❌ INCORRECT: Using any type
function processData(data: any): any {
  return data; // Unsafe and loses type information
}

// ✅ CORRECT: Proper typing with validation
function processData(data: unknown): UserConfigType {
  return UserConfig.parse(data); // Validates at runtime
}

Implementation Steps

1. Install Zod: npm install zod
2. Define Schema: Create Zod schema with proper constraints
3. Infer Type: Use z.infer<typeof SchemaName> for TypeScript types
4. Export Both: Export schema for runtime validation, type for compile-time checking
5. Validate Input: Use schema.parse() or schema.safeParse() for validation

2. Error Handling

Rules

• ALWAYS use custom error classes extending GatewayError
• ALWAYS provide meaningful error messages with context
• ALWAYS handle errors gracefully with proper logging
• NEVER let unhandled errors bubble up

Instructions

// ✅ CORRECT: Custom error class with context
import { GatewayError } from "./errors";

export class ProviderConnectionError extends GatewayError {
  constructor(
    message: string,
    public readonly provider: string,
    public readonly statusCode: number,
    public readonly originalError?: Error
  ) {
    super(`Failed to connect to ${provider}: ${message} (Status: ${statusCode})`, "PROVIDER_CONNECTION_ERROR");
  }
}

// Usage in code
try {
  await provider.makeRequest();
} catch (error) {
  if (error instanceof HttpError) {
    throw new ProviderConnectionError("API request failed", "anthropic", error.status, error);
  }
  throw error;
}