Skip to content
ai.matey

API Reference

Complete API documentation for all ai.matey packages.

Core API

Section titled “Core API”

Comprehensive reference for the core ai.matey APIs:

Bridge API

Section titled “Bridge API”

Complete reference for the Bridge class - connecting frontend and backend adapters.

  • Constructor and configuration
  • Request/response methods (chat, chatStream, execute)
  • Middleware management
  • Event handling
  • Error handling

View Bridge API →

Router API

Section titled “Router API”

Complete reference for the Router class - intelligent multi-backend routing.

  • Routing strategies (round-robin, priority, weighted, custom)
  • Backend management
  • Health monitoring
  • Failover and fallback
  • Advanced routing patterns

View Router API →

Middleware API

Section titled “Middleware API”

Complete reference for all built-in middleware and the Middleware interface.

  • Logging, caching, retry, transform
  • Cost tracking, rate limiting, validation
  • OpenTelemetry tracing
  • Creating custom middleware
  • Middleware composition

View Middleware API →

Types API

Section titled “Types API”

Complete TypeScript type definitions.

  • IR types (IRChatCompletionRequest, IRChatCompletionResponse, etc.)
  • Adapter interfaces (BackendAdapter, FrontendAdapter)
  • Configuration types (BridgeOptions, RouterOptions)
  • Utility types and type guards

View Types API →

Errors API

Section titled “Errors API”

Complete error handling reference.

  • Error hierarchy (AIMateyError, BackendError, ValidationError, etc.)
  • Error codes and descriptions
  • Error handling patterns
  • Best practices

View Errors API →

Core Packages

Section titled “Core Packages”

ai.matey.core

Section titled “ai.matey.core”

The foundational package containing Bridge, Router, and core functionality.

Key Exports:

  • Bridge - Connect frontend and backend adapters → API
  • Router - Route requests to multiple backends → API
  • MiddlewareStack - Manage middleware chain

View Package Documentation →

ai.matey.types

Section titled “ai.matey.types”

TypeScript type definitions for all packages.

Key Types:

  • IRChatCompletionRequest - Intermediate Representation request format
  • IRChatCompletionResponse - IR response format
  • IRChatCompletionChunk - Streaming chunk format
  • BackendAdapter - Backend interface
  • FrontendAdapter - Frontend interface
  • Middleware - Middleware interface

View Full API Documentation →

ai.matey.errors

Section titled “ai.matey.errors”

Error classes and utilities.

Key Exports:

  • AIMateyError - Base error class
  • BackendError - Backend-specific errors
  • RateLimitError - Rate limit exceeded
  • AuthenticationError - Invalid API key
  • ValidationError - Request validation failed

View Full API Documentation →

Adapter Packages

Section titled “Adapter Packages”

Frontend Adapters

Section titled “Frontend Adapters”

Parse different input formats into IR.

  • ai.matey.frontend/openai - OpenAI chat completion format
  • ai.matey.frontend/anthropic - Anthropic messages API format
  • ai.matey.frontend/gemini - Google Gemini format
  • ai.matey.frontend/mistral - Mistral format
  • ai.matey.frontend/ollama - Ollama format
  • ai.matey.frontend/groq - Groq format
  • ai.matey.frontend/generic - Generic IR format

View Frontend Adapters →

Backend Adapters

Section titled “Backend Adapters”

Convert IR to provider-specific formats and execute requests.

24 Supported Providers:

  • ai.matey.backend/openai
  • ai.matey.backend/anthropic
  • ai.matey.backend/gemini
  • ai.matey.backend/mistral
  • ai.matey.backend/ollama
  • ai.matey.backend/groq
  • … and 18 more

View All Backend Providers →

Middleware Packages

Section titled “Middleware Packages”

ai.matey.middleware

Section titled “ai.matey.middleware”

Built-in middleware for common use cases.

Available Middleware:

  • createLoggingMiddleware() - Request/response logging
  • createCachingMiddleware() - Response caching
  • createRetryMiddleware() - Automatic retry with backoff
  • createTransformMiddleware() - Request/response transformation
  • createCostTrackingMiddleware() - Track API costs
  • createOpenTelemetryMiddleware() - Distributed tracing
  • createRateLimitMiddleware() - Rate limiting
  • createValidationMiddleware() - Request validation
  • createSecurityMiddleware() - Security headers
  • createConversationHistoryMiddleware() - Conversation state

View Middleware Guide →

Integration Packages

Section titled “Integration Packages”

ai.matey.http

Section titled “ai.matey.http”

HTTP server integration for Express, Fastify, Hono, and Node.js http.

Key Exports:

  • ExpressMiddleware - Express.js integration
  • FastifyPlugin - Fastify plugin
  • HonoMiddleware - Hono middleware
  • NodeHTTPListener - Node.js http integration

View Examples →

Section titled “Quick Links”

By Use Case

Section titled “By Use Case”

By Package

Section titled “By Package”

Common Interfaces

Section titled “Common Interfaces”

BackendAdapter Interface

Section titled “BackendAdapter Interface”
interface BackendAdapter {
  execute(request: IRChatCompletionRequest): Promise<IRChatCompletionResponse>;
  executeStream(request: IRChatCompletionRequest): Promise<AsyncIterable<IRChatCompletionChunk>>;
  checkHealth?(): Promise<boolean>;
}

FrontendAdapter Interface

Section titled “FrontendAdapter Interface”
interface FrontendAdapter {
  parseRequest(input: any): IRChatCompletionRequest;
  formatResponse(ir: IRChatCompletionResponse): any;
}

Middleware Interface

Section titled “Middleware Interface”
interface Middleware {
  onRequest?(request: IRChatCompletionRequest): Promise<IRChatCompletionRequest>;
  onResponse?(response: IRChatCompletionResponse): Promise<IRChatCompletionResponse>;
  onError?(error: Error): Promise<Error | void>;
}

TypeScript Support

Section titled “TypeScript Support”

All packages include full TypeScript definitions. Import types:

import type {
  IRChatCompletionRequest,
  IRChatCompletionResponse,
  IRChatCompletionChunk,
  BackendAdapter,
  FrontendAdapter,
  Middleware
} from 'ai.matey.types';

Version Compatibility

Section titled “Version Compatibility”

All ai.matey packages use synchronized versioning. Always use matching versions across packages:

{
  "dependencies": {
    "ai.matey.core": "^0.2.0",
    "ai.matey.frontend": "^0.2.0",
    "ai.matey.backend": "^0.2.0"
  }
}

Auto-Generated Documentation

Section titled “Auto-Generated Documentation”

Detailed API documentation is auto-generated from TypeScript source code using TypeDoc:

Contributing

Section titled “Contributing”

Found an issue with the API? Want to request a new feature?

Explore the API: