@theihtisham/ai-agent-starter-kit 1.0.0

package/src/lib/ai/models.ts

@@ -0,0 +1,80 @@
+export type AIProvider = 'openai' | 'anthropic' | 'google' | 'custom';
+
+export interface ModelConfig {
+  id: string;
+  name: string;
+  provider: AIProvider;
+  maxTokens: number;
+  supportsTools: boolean;
+  supportsStreaming: boolean;
+  pricing: {
+    inputPer1k: number;
+    outputPer1k: number;
+  };
+}
+
+export const AVAILABLE_MODELS: ModelConfig[] = [
+  {
+    id: 'gpt-4o',
+    name: 'GPT-4o',
+    provider: 'openai',
+    maxTokens: 128000,
+    supportsTools: true,
+    supportsStreaming: true,
+    pricing: { inputPer1k: 0.0025, outputPer1k: 0.01 },
+  },
+  {
+    id: 'gpt-4o-mini',
+    name: 'GPT-4o Mini',
+    provider: 'openai',
+    maxTokens: 128000,
+    supportsTools: true,
+    supportsStreaming: true,
+    pricing: { inputPer1k: 0.00015, outputPer1k: 0.0006 },
+  },
+  {
+    id: 'gpt-4-turbo',
+    name: 'GPT-4 Turbo',
+    provider: 'openai',
+    maxTokens: 128000,
+    supportsTools: true,
+    supportsStreaming: true,
+    pricing: { inputPer1k: 0.01, outputPer1k: 0.03 },
+  },
+  {
+    id: 'claude-sonnet-4-6',
+    name: 'Claude Sonnet 4.6',
+    provider: 'anthropic',
+    maxTokens: 200000,
+    supportsTools: true,
+    supportsStreaming: true,
+    pricing: { inputPer1k: 0.003, outputPer1k: 0.015 },
+  },
+  {
+    id: 'claude-haiku-4-5',
+    name: 'Claude Haiku 4.5',
+    provider: 'anthropic',
+    maxTokens: 200000,
+    supportsTools: true,
+    supportsStreaming: true,
+    pricing: { inputPer1k: 0.0008, outputPer1k: 0.004 },
+  },
+  {
+    id: 'gemini-2.5-flash',
+    name: 'Gemini 2.5 Flash',
+    provider: 'google',
+    maxTokens: 1000000,
+    supportsTools: true,
+    supportsStreaming: true,
+    pricing: { inputPer1k: 0.000075, outputPer1k: 0.0003 },
+  },
+];
+
+export function getModel(modelId: string): ModelConfig | undefined {
+  return AVAILABLE_MODELS.find((m) => m.id === modelId);
+}
+
+export function getProviderForModel(modelId: string): AIProvider {
+  const model = getModel(modelId);
+  return model?.provider ?? 'openai';
+}

package/src/lib/ai/streaming.ts

@@ -0,0 +1,80 @@
+/**
+ * Server-Sent Events (SSE) streaming helper for chat responses.
+ */
+
+export interface StreamChunk {
+  type: 'text' | 'tool_call' | 'tool_result' | 'error' | 'done';
+  content: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Create a ReadableStream that emits SSE-formatted chunks
+ */
+export function createSSEStream(): {
+  stream: ReadableStream<Uint8Array>;
+  controller: ReadableStreamDefaultController<Uint8Array>;
+  send: (chunk: StreamChunk) => void;
+  close: () => void;
+} {
+  const encoder = new TextEncoder();
+  let controller: ReadableStreamDefaultController<Uint8Array> | null = null;
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(c) {
+      controller = c;
+    },
+  });
+
+  const send = (chunk: StreamChunk) => {
+    if (!controller) return;
+    const data = `data: ${JSON.stringify(chunk)}\n\n`;
+    controller.enqueue(encoder.encode(data));
+  };
+
+  const close = () => {
+    if (!controller) return;
+    send({ type: 'done', content: '' });
+    controller.close();
+  };
+
+  return { stream, controller: controller!, send, close };
+}
+
+/**
+ * Parse an SSE stream from a fetch Response into async generator of chunks
+ */
+export async function* parseSSEStream(
+  response: Response,
+): AsyncGenerator<StreamChunk> {
+  const reader = response.body?.getReader();
+  if (!reader) throw new Error('No response body');
+
+  const decoder = new TextDecoder();
+  let buffer = '';
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split('\n');
+      buffer = lines.pop() ?? '';
+
+      for (const line of lines) {
+        if (line.startsWith('data: ')) {
+          const data = line.slice(6).trim();
+          if (data === '[DONE]') return;
+          try {
+            yield JSON.parse(data) as StreamChunk;
+          } catch {
+            // Skip malformed chunks
+          }
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}

package/src/lib/ai/tools.ts

@@ -0,0 +1,149 @@
+/**
+ * Built-in tools registry for AI agents.
+ * Each tool defines its schema and handler function.
+ */
+
+export interface ToolDefinition {
+  id: string;
+  name: string;
+  description: string;
+  parameters: Record<string, {
+    type: string;
+    description: string;
+    required?: boolean;
+    enum?: string[];
+  }>;
+  handler: (params: Record<string, unknown>) => Promise<string>;
+}
+
+export const builtInTools: Record<string, ToolDefinition> = {};
+
+export function registerTool(tool: ToolDefinition): void {
+  builtInTools[tool.id] = tool;
+}
+
+export function getTool(toolId: string): ToolDefinition | undefined {
+  return builtInTools[toolId];
+}
+
+export function getAllTools(): ToolDefinition[] {
+  return Object.values(builtInTools);
+}
+
+export function getToolsByIds(ids: string[]): ToolDefinition[] {
+  return ids.map((id) => builtInTools[id]).filter((t): t is ToolDefinition => t != null);
+}
+
+// --- Web Search Tool ---
+registerTool({
+  id: 'web_search',
+  name: 'Web Search',
+  description: 'Search the web for information. Returns top results with titles, URLs, and snippets.',
+  parameters: {
+    query: { type: 'string', description: 'Search query', required: true },
+    max_results: { type: 'number', description: 'Max results to return (1-10)', required: false },
+  },
+  handler: async (params) => {
+    const query = params.query as string;
+    const maxResults = Math.min((params.max_results as number) ?? 5, 10);
+    // Placeholder: in production, use SearXNG, SerpAPI, or Google Custom Search
+    return `Search results for "${query}" (top ${maxResults}):\n[Web search not configured — set SEARXNG_URL or SERP_API_KEY env var]`;
+  },
+});
+
+// --- Calculator Tool ---
+registerTool({
+  id: 'calculator',
+  name: 'Calculator',
+  description: 'Evaluate mathematical expressions safely.',
+  parameters: {
+    expression: { type: 'string', description: 'Math expression to evaluate (e.g., "2 + 2", "Math.sqrt(16)")', required: true },
+  },
+  handler: async (params) => {
+    const expression = params.expression as string;
+    try {
+      // Safe evaluation using Function constructor with restricted scope
+      const allowedMath = {
+        abs: Math.abs, ceil: Math.ceil, floor: Math.floor, round: Math.round,
+        sqrt: Math.sqrt, pow: Math.pow, log: Math.log, log2: Math.log2,
+        sin: Math.sin, cos: Math.cos, tan: Math.tan, PI: Math.PI, E: Math.E,
+        min: Math.min, max: Math.max, random: Math.random,
+      };
+      const keys = Object.keys(allowedMath);
+      const values = Object.values(allowedMath);
+      const fn = new Function(...keys, `"use strict"; return (${expression});`);
+      const result = fn(...values);
+      return `Result: ${result}`;
+    } catch (err) {
+      return `Error evaluating expression: ${(err as Error).message}`;
+    }
+  },
+});
+
+// --- JSON Parser Tool ---
+registerTool({
+  id: 'json_parser',
+  name: 'JSON Parser',
+  description: 'Parse and query JSON data. Supports JSONPath-like queries.',
+  parameters: {
+    data: { type: 'string', description: 'JSON string to parse', required: true },
+    query: { type: 'string', description: 'Optional dot-notation path (e.g., "users[0].name")', required: false },
+  },
+  handler: async (params) => {
+    const data = params.data as string;
+    const query = params.query as string | undefined;
+    try {
+      let parsed = JSON.parse(data);
+      if (query) {
+        const parts = query.replace(/\[(\d+)]/g, '.$1').split('.');
+        for (const part of parts) {
+          if (part === '') continue;
+          parsed = parsed[part];
+          if (parsed === undefined) return `Path "${query}" not found in JSON`;
+        }
+      }
+      return JSON.stringify(parsed, null, 2);
+    } catch (err) {
+      return `JSON parse error: ${(err as Error).message}`;
+    }
+  },
+});
+
+// --- Code Executor Tool (safe sandbox) ---
+registerTool({
+  id: 'code_executor',
+  name: 'Code Executor',
+  description: 'Execute JavaScript code in a safe sandbox. Read-only access, no filesystem.',
+  parameters: {
+    code: { type: 'string', description: 'JavaScript code to execute', required: true },
+    language: { type: 'string', description: 'Language (currently only "javascript")', required: false, enum: ['javascript'] },
+  },
+  handler: async (params) => {
+    const code = params.code as string;
+    try {
+      const fn = new Function('"use strict"; ' + code);
+      const result = fn();
+      return `Output: ${JSON.stringify(result, null, 2)}`;
+    } catch (err) {
+      return `Execution error: ${(err as Error).message}`;
+    }
+  },
+});
+
+// --- File Reader Tool ---
+registerTool({
+  id: 'file_reader',
+  name: 'File Reader',
+  description: 'Read file contents. Supports text files, JSON, CSV.',
+  parameters: {
+    file_content: { type: 'string', description: 'The file content to analyze', required: true },
+    filename: { type: 'string', description: 'Name of the file', required: true },
+  },
+  handler: async (params) => {
+    const content = params.file_content as string;
+    const filename = params.filename as string;
+    const lines = content.split('\n').length;
+    const chars = content.length;
+    return `File: ${filename}\nLines: ${lines}, Characters: ${chars}\n\nContent preview:\n${content.slice(0, 2000)}${content.length > 2000 ? '\n...[truncated]' : ''}`;
+  },
+});

package/src/lib/auth/middleware.ts

@@ -0,0 +1,41 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getToken } from 'next-auth/jwt';
+
+const PUBLIC_PATHS = ['/', '/login', '/signup', '/forgot-password', '/pricing', '/api/auth', '/api/health'];
+const PUBLIC_API_PREFIXES = ['/api/stripe/webhook'];
+
+export async function authMiddleware(req: NextRequest) {
+  const { pathname } = req.nextUrl;
+
+  // Allow public paths
+  if (PUBLIC_PATHS.some((p) => pathname === p || pathname.startsWith(p + '/'))) {
+    return NextResponse.next();
+  }
+
+  // Allow webhook endpoints (verified by signature)
+  if (PUBLIC_API_PREFIXES.some((p) => pathname.startsWith(p))) {
+    return NextResponse.next();
+  }
+
+  // Allow static files and Next.js internals
+  if (pathname.startsWith('/_next') || pathname.startsWith('/favicon') || pathname.includes('.')) {
+    return NextResponse.next();
+  }
+
+  // Check JWT token
+  const token = await getToken({ req, secret: process.env.NEXTAUTH_SECRET });
+
+  if (!token) {
+    // API routes return 401
+    if (pathname.startsWith('/api/')) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+    // Page routes redirect to login
+    const loginUrl = req.nextUrl.clone();
+    loginUrl.pathname = '/login';
+    loginUrl.searchParams.set('callbackUrl', pathname);
+    return NextResponse.redirect(loginUrl);
+  }
+
+  return NextResponse.next();
+}

package/src/lib/auth/nextauth.ts

@@ -0,0 +1,69 @@
+import type { NextAuthOptions } from 'next-auth';
+import GoogleProvider from 'next-auth/providers/google';
+import GitHubProvider from 'next-auth/providers/github';
+import EmailProvider from 'next-auth/providers/email';
+import { PrismaAdapter } from '@next-auth/prisma-adapter';
+import prisma from '../db/client';
+
+export const authOptions: NextAuthOptions = {
+  adapter: PrismaAdapter(prisma),
+  providers: [
+    ...(process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET
+      ? [
+          GoogleProvider({
+            clientId: process.env.GOOGLE_CLIENT_ID,
+            clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+          }),
+        ]
+      : []),
+    ...(process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET
+      ? [
+          GitHubProvider({
+            clientId: process.env.GITHUB_CLIENT_ID,
+            clientSecret: process.env.GITHUB_CLIENT_SECRET,
+          }),
+        ]
+      : []),
+    ...(process.env.RESEND_API_KEY
+      ? [
+          EmailProvider({
+            server: {
+              host: 'smtp.resend.com',
+              port: 465,
+              auth: {
+                user: 'resend',
+                pass: process.env.RESEND_API_KEY,
+              },
+            },
+            from: process.env.EMAIL_FROM ?? 'noreply@yourdomain.com',
+          }),
+        ]
+      : []),
+  ],
+  session: {
+    strategy: 'jwt',
+    maxAge: 30 * 24 * 60 * 60, // 30 days
+  },
+  pages: {
+    signIn: '/login',
+    error: '/login',
+  },
+  callbacks: {
+    async jwt({ token, user }) {
+      if (user) {
+        token.id = user.id;
+        token.email = user.email;
+      }
+      return token;
+    },
+    async session({ session, token }) {
+      if (session.user && token.id) {
+        session.user.id = token.id as string;
+        session.user.email = token.email as string;
+      }
+      return session;
+    },
+  },
+  secret: process.env.NEXTAUTH_SECRET,
+  debug: process.env.NODE_ENV === 'development',
+};

package/src/lib/db/client.ts

@@ -0,0 +1,15 @@
+import { PrismaClient } from '@prisma/client';
+
+const globalForPrisma = globalThis as unknown as {
+  prisma: PrismaClient | undefined;
+};
+
+export const prisma = globalForPrisma.prisma ?? new PrismaClient({
+  log: process.env.NODE_ENV === 'development' ? ['query', 'error', 'warn'] : ['error'],
+});
+
+if (process.env.NODE_ENV !== 'production') {
+  globalForPrisma.prisma = prisma;
+}
+
+export default prisma;

package/src/lib/rate-limit/limiter.ts

@@ -0,0 +1,93 @@
+import { logger } from '../utils/logger';
+
+interface RateLimitEntry {
+  count: number;
+  resetAt: number;
+}
+
+const store = new Map<string, RateLimitEntry>();
+
+// Cleanup old entries every 5 minutes
+setInterval(() => {
+  const now = Date.now();
+  const keysToDelete: string[] = [];
+  store.forEach((entry, key) => {
+    if (entry.resetAt < now) {
+      keysToDelete.push(key);
+    }
+  });
+  keysToDelete.forEach((key) => store.delete(key));
+}, 5 * 60 * 1000);
+
+export interface RateLimitResult {
+  allowed: boolean;
+  remaining: number;
+  limit: number;
+  resetAt: number;
+}
+
+/**
+ * Sliding window rate limiter.
+ * Uses in-memory store by default, Redis when REDIS_URL is set.
+ */
+export async function rateLimit(
+  key: string,
+  limit: number,
+  windowMs: number,
+): Promise<RateLimitResult> {
+  // If Redis is available, use it for distributed rate limiting
+  if (process.env.REDIS_URL) {
+    return redisRateLimit(key, limit, windowMs);
+  }
+
+  return memoryRateLimit(key, limit, windowMs);
+}
+
+function memoryRateLimit(key: string, limit: number, windowMs: number): RateLimitResult {
+  const now = Date.now();
+  const entry = store.get(key);
+
+  if (!entry || entry.resetAt < now) {
+    store.set(key, { count: 1, resetAt: now + windowMs });
+    return { allowed: true, remaining: limit - 1, limit, resetAt: now + windowMs };
+  }
+
+  if (entry.count >= limit) {
+    return { allowed: false, remaining: 0, limit, resetAt: entry.resetAt };
+  }
+
+  entry.count++;
+  return { allowed: true, remaining: limit - entry.count, limit, resetAt: entry.resetAt };
+}
+
+async function redisRateLimit(key: string, limit: number, windowMs: number): Promise<RateLimitResult> {
+  const redisKey = `ratelimit:${key}`;
+  const resetAt = Date.now() + windowMs;
+
+  try {
+    // Dynamic import for optional redis dependency
+    const { createClient } = await import('redis');
+    const client = createClient({ url: process.env.REDIS_URL });
+    await client.connect();
+
+    const count = await client.incr(redisKey);
+    if (count === 1) {
+      await client.pExpire(redisKey, windowMs);
+    }
+
+    const ttl = await client.pTTL(redisKey);
+    const remaining = Math.max(0, limit - count);
+
+    await client.disconnect();
+
+    return {
+      allowed: count <= limit,
+      remaining,
+      limit,
+      resetAt: Date.now() + ttl,
+    };
+  } catch (err) {
+    logger.warn('Redis rate limit failed, falling back to memory', { error: (err as Error).message });
+    return memoryRateLimit(key, limit, windowMs);
+  }
+}

package/src/lib/rate-limit/rules.ts

@@ -0,0 +1,38 @@
+import { getPlan } from '../stripe/plans';
+import { rateLimit, type RateLimitResult } from './limiter';
+
+interface RateLimitRule {
+  windowMs: number;
+  limit: number;
+}
+
+const RULES: Record<string, RateLimitRule> = {
+  // Per-endpoint rate limits
+  'chat:message': { windowMs: 60 * 1000, limit: 20 },        // 20 messages/minute
+  'chat:stream': { windowMs: 60 * 1000, limit: 20 },         // 20 streams/minute
+  'agent:create': { windowMs: 60 * 1000, limit: 10 },        // 10 agent creates/minute
+  'agent:update': { windowMs: 60 * 1000, limit: 30 },        // 30 updates/minute
+  'api-key:create': { windowMs: 60 * 60 * 1000, limit: 5 },  // 5 API keys/hour
+  'auth:login': { windowMs: 15 * 60 * 1000, limit: 10 },     // 10 login attempts/15min
+  'auth:signup': { windowMs: 60 * 60 * 1000, limit: 5 },     // 5 signups/hour
+  'api:general': { windowMs: 60 * 1000, limit: 60 },         // 60 requests/minute
+};
+
+/**
+ * Apply rate limiting based on plan and action type.
+ * Pro/Team plans get 2x/5x the limits.
+ */
+export async function applyRateLimit(
+  userId: string,
+  action: string,
+  planId: string = 'free',
+): Promise<RateLimitResult> {
+  const rule = RULES[action] ?? RULES['api:general']!;
+  const plan = getPlan(planId);
+
+  // Scale limits by plan tier
+  const multiplier = plan.id === 'team' ? 5 : plan.id === 'pro' ? 2 : 1;
+  const limit = rule.limit * multiplier;
+
+  return rateLimit(`rl:${userId}:${action}`, limit, rule.windowMs);
+}

package/src/lib/stripe/client.ts

@@ -0,0 +1,25 @@
+import Stripe from 'stripe';
+
+let _stripe: Stripe | null = null;
+
+export function getStripeClient(): Stripe {
+  if (!_stripe) {
+    const key = process.env.STRIPE_SECRET_KEY;
+    if (!key) {
+      throw new Error('STRIPE_SECRET_KEY is not configured');
+    }
+    _stripe = new Stripe(key, {
+      typescript: true,
+    } as Stripe.StripeConfig);
+  }
+  return _stripe;
+}
+
+// Lazy getter — only creates client when accessed
+export const stripe = new Proxy({} as Stripe, {
+  get(_target, prop) {
+    const client = getStripeClient();
+    const value = (client as unknown as Record<string | symbol, unknown>)[prop];
+    return typeof value === 'function' ? value.bind(client) : value;
+  },
+});

package/src/lib/stripe/plans.ts

@@ -0,0 +1,75 @@
+export interface Plan {
+  id: string;
+  name: string;
+  price: number;
+  interval: 'month' | 'year';
+  stripePriceId: string;
+  features: {
+    maxAgents: number;
+    maxMessages: number;
+    maxTokens: number;
+    tools: boolean;
+    apiAccess: boolean;
+    support: string;
+    customTools: boolean;
+  };
+}
+
+export const PLANS: Plan[] = [
+  {
+    id: 'free',
+    name: 'Free',
+    price: 0,
+    interval: 'month',
+    stripePriceId: '',
+    features: {
+      maxAgents: 2,
+      maxMessages: 50,
+      maxTokens: 100000,
+      tools: false,
+      apiAccess: false,
+      support: 'Community',
+      customTools: false,
+    },
+  },
+  {
+    id: 'pro',
+    name: 'Pro',
+    price: 19,
+    interval: 'month',
+    stripePriceId: process.env.STRIPE_PRO_PRICE_ID ?? '',
+    features: {
+      maxAgents: 10,
+      maxMessages: 2000,
+      maxTokens: 2000000,
+      tools: true,
+      apiAccess: true,
+      support: 'Email',
+      customTools: false,
+    },
+  },
+  {
+    id: 'team',
+    name: 'Team',
+    price: 49,
+    interval: 'month',
+    stripePriceId: process.env.STRIPE_TEAM_PRICE_ID ?? '',
+    features: {
+      maxAgents: 50,
+      maxMessages: 10000,
+      maxTokens: 10000000,
+      tools: true,
+      apiAccess: true,
+      support: 'Priority',
+      customTools: true,
+    },
+  },
+];
+
+export function getPlan(planId: string): Plan {
+  return PLANS.find((p) => p.id === planId) ?? PLANS[0]!;
+}
+
+export function getPlanByPriceId(stripePriceId: string): Plan | undefined {
+  return PLANS.find((p) => p.stripePriceId === stripePriceId);
+}