ai.matey.http.core 0.2.0

package/dist/types/types.d.ts

@@ -0,0 +1,398 @@
+/**
+ * HTTP Core Types
+ *
+ * Unified type definitions for the HTTP adapter system.
+ * These types allow us to write core logic once and adapt it to any framework.
+ *
+ * @module
+ */
+import type { IncomingMessage, ServerResponse } from 'http';
+import type { Bridge } from 'ai.matey.core';
+import type { FrontendAdapter } from 'ai.matey.types';
+/**
+ * CORS configuration options
+ */
+export interface CORSOptions {
+    /**
+     * Allowed origins (default: '*')
+     */
+    origin?: string | string[] | ((origin: string) => boolean);
+    /**
+     * Allowed HTTP methods (default: 'GET, POST, OPTIONS')
+     */
+    methods?: string | string[];
+    /**
+     * Allowed headers (default: 'Content-Type, Authorization')
+     */
+    allowedHeaders?: string | string[];
+    /**
+     * Exposed headers
+     */
+    exposedHeaders?: string | string[];
+    /**
+     * Allow credentials (default: true)
+     */
+    credentials?: boolean;
+    /**
+     * Max age for preflight cache in seconds (default: 86400)
+     */
+    maxAge?: number;
+}
+/**
+ * Route matching configuration
+ */
+export interface RouteConfig {
+    /**
+     * Path pattern to match (supports simple wildcards)
+     * Examples: '/v1/chat/completions', '/v1/messages', '/v1/*'
+     */
+    path: string;
+    /**
+     * HTTP methods to match (default: ['POST'])
+     */
+    methods?: string[];
+    /**
+     * Frontend adapter to use for this route
+     */
+    frontend: FrontendAdapter;
+    /**
+     * Optional bridge to use (overrides default)
+     */
+    bridge?: Bridge;
+}
+/**
+ * Matched route information
+ */
+export interface MatchedRoute {
+    /**
+     * Route configuration
+     */
+    config: RouteConfig;
+    /**
+     * Path parameters (if any)
+     */
+    params: Record<string, string>;
+}
+/**
+ * Generic HTTP request interface (framework-agnostic)
+ */
+export interface GenericRequest {
+    /**
+     * HTTP method (GET, POST, etc.)
+     */
+    method: string;
+    /**
+     * Full request URL
+     */
+    url: string;
+    /**
+     * Request headers (normalized to lowercase keys)
+     */
+    headers: Record<string, string>;
+    /**
+     * Parsed request body (null if not yet parsed)
+     */
+    body: any;
+    /**
+     * URL parameters (e.g., /users/:id -> { id: '123' })
+     */
+    params?: Record<string, string>;
+    /**
+     * Query string parameters
+     */
+    query?: Record<string, string>;
+    /**
+     * Client IP address
+     */
+    ip?: string;
+}
+/**
+ * Generic HTTP response interface (framework-agnostic)
+ */
+export interface GenericResponse {
+    /**
+     * Set HTTP status code
+     */
+    status(code: number): void;
+    /**
+     * Set response header
+     */
+    header(name: string, value: string): void;
+    /**
+     * Send JSON response
+     */
+    send(data: any): void;
+    /**
+     * Send streaming response (SSE)
+     */
+    stream(generator: AsyncGenerator<any, void, undefined>): Promise<void>;
+    /**
+     * Check if response is writable
+     */
+    isWritable(): boolean;
+}
+/**
+ * Parsed HTTP request (after body parsing)
+ */
+export interface ParsedGenericRequest extends GenericRequest {
+    /**
+     * Parsed request body (guaranteed to be parsed)
+     */
+    body: any;
+    /**
+     * Whether streaming is requested
+     */
+    stream?: boolean;
+}
+/**
+ * Auth validator for generic requests
+ */
+export type GenericAuthValidator = (req: GenericRequest) => boolean | Promise<boolean>;
+/**
+ * Error handler for generic requests/responses
+ */
+export type GenericErrorHandler = (error: Error, req: GenericRequest, res: GenericResponse) => void | Promise<void>;
+/**
+ * Rate limit key generator for generic requests
+ */
+export type GenericRateLimitKeyGenerator = (req: GenericRequest) => string;
+/**
+ * Rate limit handler for generic requests/responses
+ */
+export type GenericRateLimitHandler = (req: GenericRequest, res: GenericResponse, retryAfter: number) => void | Promise<void>;
+/**
+ * Generic rate limit options
+ */
+export interface GenericRateLimitOptions {
+    /**
+     * Maximum number of requests per window
+     */
+    max: number;
+    /**
+     * Time window in milliseconds (default: 60000 = 1 minute)
+     */
+    windowMs?: number;
+    /**
+     * Generate rate limit key from request (default: IP address)
+     */
+    keyGenerator?: GenericRateLimitKeyGenerator;
+    /**
+     * Handler called when rate limit exceeded
+     */
+    handler?: GenericRateLimitHandler;
+    /**
+     * Skip rate limiting for certain requests
+     */
+    skip?: (req: GenericRequest) => boolean | Promise<boolean>;
+    /**
+     * Custom headers to include in rate limit responses
+     */
+    headers?: boolean;
+}
+/**
+ * Core handler options
+ */
+export interface CoreHandlerOptions {
+    /**
+     * Bridge instance connecting frontend and backend adapters
+     */
+    bridge: Bridge;
+    /**
+     * CORS configuration
+     */
+    cors?: CORSOptions;
+    /**
+     * Authentication validator
+     */
+    validateAuth?: GenericAuthValidator;
+    /**
+     * Error handler
+     */
+    onError?: GenericErrorHandler;
+    /**
+     * Custom response headers
+     */
+    headers?: Record<string, string>;
+    /**
+     * Request timeout in milliseconds
+     */
+    timeout?: number;
+    /**
+     * Path prefix for all routes
+     */
+    pathPrefix?: string;
+    /**
+     * Rate limiting configuration
+     */
+    rateLimit?: GenericRateLimitOptions;
+    /**
+     * Route configurations for multi-endpoint support
+     */
+    routes?: RouteConfig[];
+    /**
+     * Enable request/response logging
+     */
+    logging?: boolean;
+    /**
+     * Log function
+     */
+    log?: (message: string, ...args: any[]) => void;
+    /**
+     * Maximum request body size in bytes
+     */
+    maxBodySize?: number;
+    /**
+     * Enable streaming support
+     */
+    streaming?: boolean;
+}
+/**
+ * HTTP request handler compatible with Node.js http.createServer
+ */
+export type HTTPRequestHandler = (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+/**
+ * Auth validator function (Node.js-specific)
+ * @deprecated Use GenericAuthValidator for framework-agnostic code
+ */
+export type AuthValidator = (req: IncomingMessage) => boolean | Promise<boolean>;
+/**
+ * Error handler function (Node.js-specific)
+ * @deprecated Use GenericErrorHandler for framework-agnostic code
+ */
+export type ErrorHandler = (error: Error, req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+/**
+ * Rate limit key generator (Node.js-specific)
+ * @deprecated Use GenericRateLimitKeyGenerator for framework-agnostic code
+ */
+export type RateLimitKeyGenerator = (req: IncomingMessage) => string;
+/**
+ * Rate limit handler (called when limit exceeded) (Node.js-specific)
+ * @deprecated Use GenericRateLimitHandler for framework-agnostic code
+ */
+export type RateLimitHandler = (req: IncomingMessage, res: ServerResponse, retryAfter: number) => void | Promise<void>;
+/**
+ * Rate limiting configuration (Node.js-specific)
+ */
+export interface RateLimitOptions {
+    /**
+     * Maximum number of requests per window
+     */
+    max: number;
+    /**
+     * Time window in milliseconds (default: 60000 = 1 minute)
+     */
+    windowMs?: number;
+    /**
+     * Generate rate limit key from request (default: IP address)
+     */
+    keyGenerator?: RateLimitKeyGenerator;
+    /**
+     * Handler called when rate limit exceeded
+     */
+    handler?: RateLimitHandler;
+    /**
+     * Skip rate limiting for certain requests
+     */
+    skip?: (req: IncomingMessage) => boolean | Promise<boolean>;
+    /**
+     * Custom headers to include in rate limit responses
+     */
+    headers?: boolean;
+}
+/**
+ * HTTP listener configuration options
+ * Supports both Node.js-specific and generic types for framework compatibility
+ */
+export interface HTTPListenerOptions {
+    /**
+     * CORS configuration (default: enabled with sensible defaults)
+     */
+    cors?: boolean | CORSOptions;
+    /**
+     * Authentication validator (accepts both Node.js and generic types)
+     */
+    validateAuth?: AuthValidator | GenericAuthValidator;
+    /**
+     * Error handler (accepts both Node.js and generic types)
+     */
+    onError?: ErrorHandler | GenericErrorHandler;
+    /**
+     * Custom response headers
+     */
+    headers?: Record<string, string>;
+    /**
+     * Request timeout in milliseconds (default: 30000)
+     */
+    timeout?: number;
+    /**
+     * Path prefix for all routes (e.g., '/v1')
+     */
+    pathPrefix?: string;
+    /**
+     * Rate limiting configuration (accepts both Node.js and generic types)
+     */
+    rateLimit?: RateLimitOptions | GenericRateLimitOptions;
+    /**
+     * Route configurations for multi-endpoint support
+     */
+    routes?: RouteConfig[];
+    /**
+     * Enable request/response logging (default: false)
+     */
+    logging?: boolean;
+    /**
+     * Log function (default: console.log)
+     */
+    log?: (message: string, ...args: any[]) => void;
+    /**
+     * Maximum request body size in bytes (default: 10MB)
+     */
+    maxBodySize?: number;
+    /**
+     * Enable streaming support (default: true)
+     */
+    streaming?: boolean;
+}
+/**
+ * Parsed HTTP request
+ */
+export interface ParsedRequest {
+    /**
+     * Request body (parsed JSON)
+     */
+    body: any;
+    /**
+     * Request headers
+     */
+    headers: Record<string, string>;
+    /**
+     * Request path (without query string)
+     */
+    path: string;
+    /**
+     * HTTP method
+     */
+    method: string;
+    /**
+     * Query parameters
+     */
+    query: Record<string, string>;
+    /**
+     * Whether streaming is requested
+     */
+    stream?: boolean;
+}
+/**
+ * Rate limit state
+ */
+export interface RateLimitState {
+    /**
+     * Number of requests in current window
+     */
+    count: number;
+    /**
+     * Window start timestamp
+     */
+    resetTime: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "ai.matey.http.core",
+  "version": "0.2.0",
+  "description": "Framework-agnostic HTTP core utilities for AI Matey",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "readme.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs && npm run build:types",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "ai.matey.types": "*",
+    "ai.matey.errors": "*",
+    "ai.matey.core": "*"
+  },
+  "devDependencies": {
+    "ai.matey.testing": "*",
+    "@types/node": "^24.7.2",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "http",
+    "server",
+    "adapter",
+    "framework-agnostic",
+    "ai-matey"
+  ],
+  "author": "AI Matey",
+  "license": "MIT",
+  "homepage": "https://github.com/johnhenry/ai.matey#readme",
+  "bugs": {
+    "url": "https://github.com/johnhenry/ai.matey/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johnhenry/ai.matey.git",
+    "directory": "packages/http.core"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/readme.md

@@ -0,0 +1,60 @@
+# ai.matey.http.core
+
+Core HTTP utilities shared across integrations
+
+Part of the [ai.matey](https://github.com/johnhenry/ai.matey) monorepo.
+
+## Installation
+
+```bash
+npm install ai.matey.http.core
+```
+
+## Quick Start
+
+```typescript
+import { createCorsMiddleware } from 'ai.matey.http.core';
+import { Bridge } from 'ai.matey.core';
+import { OpenAIFrontendAdapter } from 'ai.matey.frontend/openai';
+import { OpenAIBackendAdapter } from 'ai.matey.backend/openai';
+
+const bridge = new Bridge(
+  new OpenAIFrontendAdapter(),
+  new OpenAIBackendAdapter({ apiKey: process.env.OPENAI_API_KEY })
+);
+
+const handler = createCorsMiddleware(bridge, {
+  streaming: true,
+  timeout: 30000,
+});
+
+// Use with your Core server
+```
+
+## API Reference
+
+### createCorsMiddleware
+
+Creates an HTTP handler for Core.
+
+```typescript
+createCorsMiddleware(bridge: Bridge, options?: HandlerOptions): Handler
+```
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `streaming` | `boolean` | `true` | Enable streaming responses |
+| `timeout` | `number` | `30000` | Request timeout in milliseconds |
+| `cors` | `boolean` | `false` | Enable CORS headers |
+
+## Exports
+
+- `createCorsMiddleware`
+- `validateApiKey`
+- `parseRequestBody`
+
+## License
+
+MIT - see [LICENSE](./LICENSE) for details.