@theihtisham/ai-agent-starter-kit 1.0.0

package/src/lib/stripe/usage.ts

@@ -0,0 +1,123 @@
+import prisma from '../db/client';
+import { getPlan } from './plans';
+import { logger } from '../utils/logger';
+
+export interface UsageCheckResult {
+  allowed: boolean;
+  remaining: number;
+  limit: number;
+  resetDate: Date;
+}
+
+/**
+ * Get current billing period usage for a user.
+ */
+export async function getUsageForPeriod(userId: string): Promise<{
+  messages: number;
+  toolCalls: number;
+  inputTokens: number;
+  outputTokens: number;
+}> {
+  const subscription = await prisma.subscription.findUnique({
+    where: { userId },
+  });
+
+  const periodStart = subscription?.currentPeriodStart ?? new Date();
+
+  const usage = await prisma.usage.findMany({
+    where: {
+      userId,
+      createdAt: { gte: periodStart },
+    },
+  });
+
+  return {
+    messages: usage.filter((u) => u.type === 'message').reduce((sum, u) => sum + u.quantity, 0),
+    toolCalls: usage.filter((u) => u.type === 'tool_call').reduce((sum, u) => sum + u.quantity, 0),
+    inputTokens: usage.filter((u) => u.type === 'token_input').reduce((sum, u) => sum + u.quantity, 0),
+    outputTokens: usage.filter((u) => u.type === 'token_output').reduce((sum, u) => sum + u.quantity, 0),
+  };
+}
+
+/**
+ * Check if user can perform an action within plan limits.
+ */
+export async function checkUsageLimit(
+  userId: string,
+  type: 'messages' | 'agents' | 'tokens',
+): Promise<UsageCheckResult> {
+  const subscription = await prisma.subscription.findUnique({ where: { userId } });
+  const planId = subscription?.stripePriceId ? 'pro' : 'free';
+  const plan = getPlan(planId);
+
+  if (type === 'agents') {
+    const agentCount = await prisma.agent.count({ where: { userId } });
+    return {
+      allowed: agentCount < plan.features.maxAgents,
+      remaining: Math.max(0, plan.features.maxAgents - agentCount),
+      limit: plan.features.maxAgents,
+      resetDate: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000),
+    };
+  }
+
+  const usage = await getUsageForPeriod(userId);
+
+  if (type === 'messages') {
+    const used = usage.messages;
+    return {
+      allowed: used < plan.features.maxMessages,
+      remaining: Math.max(0, plan.features.maxMessages - used),
+      limit: plan.features.maxMessages,
+      resetDate: subscription?.currentPeriodEnd ?? new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
+    };
+  }
+
+  // tokens
+  const used = usage.inputTokens + usage.outputTokens;
+  return {
+    allowed: used < plan.features.maxTokens,
+    remaining: Math.max(0, plan.features.maxTokens - used),
+    limit: plan.features.maxTokens,
+    resetDate: subscription?.currentPeriodEnd ?? new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
+  };
+}
+
+/**
+ * Record usage for a user action.
+ */
+export async function recordUsage(
+  userId: string,
+  type: 'message' | 'tool_call' | 'token_input' | 'token_output',
+  quantity: number,
+  metadata?: Record<string, unknown>,
+): Promise<void> {
+  await prisma.usage.create({
+    data: {
+      userId,
+      type,
+      quantity,
+      metadata: (metadata ?? {}) as never,
+    },
+  });
+
+  logger.debug('Usage recorded', { userId, type, quantity });
+}
+
+/**
+ * Get or create the Stripe customer for a user.
+ */
+export async function getOrCreateCustomer(userId: string, email: string): Promise<string> {
+  const subscription = await prisma.subscription.findUnique({ where: { userId } });
+
+  if (subscription?.stripeCustomerId) {
+    return subscription.stripeCustomerId;
+  }
+
+  const { stripe } = await import('./client');
+  const customer = await stripe.customers.create({
+    email,
+    metadata: { userId },
+  });
+
+  return customer.id;
+}

package/src/lib/stripe/webhooks.ts

@@ -0,0 +1,96 @@
+import type Stripe from 'stripe';
+import prisma from '../db/client';
+import { getPlanByPriceId } from './plans';
+import { logger } from '../utils/logger';
+
+export async function handleCheckoutComplete(session: Stripe.Checkout.Session): Promise<void> {
+  const userId = session.metadata?.userId;
+  if (!userId) {
+    logger.error('No userId in checkout session metadata');
+    return;
+  }
+
+  const plan = getPlanByPriceId(session.metadata?.priceId ?? '');
+  if (!plan) {
+    logger.error('Unknown priceId in checkout session', { priceId: session.metadata?.priceId });
+    return;
+  }
+
+  await prisma.subscription.upsert({
+    where: { userId },
+    create: {
+      userId,
+      stripeCustomerId: session.customer as string,
+      stripePriceId: plan.stripePriceId,
+      stripeSubscriptionId: session.subscription as string,
+      status: 'active',
+      currentPeriodStart: new Date(),
+      currentPeriodEnd: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
+    },
+    update: {
+      stripeCustomerId: session.customer as string,
+      stripePriceId: plan.stripePriceId,
+      stripeSubscriptionId: session.subscription as string,
+      status: 'active',
+      currentPeriodStart: new Date(),
+      currentPeriodEnd: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
+    },
+  });
+
+  logger.info('Subscription activated', { userId, plan: plan.id });
+}
+
+export async function handleSubscriptionUpdated(subscription: Stripe.Subscription): Promise<void> {
+  const sub = await prisma.subscription.findUnique({
+    where: { stripeSubscriptionId: subscription.id },
+  });
+
+  if (!sub) {
+    logger.error('Subscription not found for update', { stripeSubId: subscription.id });
+    return;
+  }
+
+  await prisma.subscription.update({
+    where: { id: sub.id },
+    data: {
+      status: subscription.status,
+      stripePriceId: subscription.items.data[0]?.price.id ?? sub.stripePriceId,
+      currentPeriodStart: new Date(subscription.current_period_start * 1000),
+      currentPeriodEnd: new Date(subscription.current_period_end * 1000),
+      cancelAtPeriodEnd: subscription.cancel_at_period_end,
+    },
+  });
+
+  logger.info('Subscription updated', { userId: sub.userId, status: subscription.status });
+}
+
+export async function handleSubscriptionDeleted(subscription: Stripe.Subscription): Promise<void> {
+  const sub = await prisma.subscription.findUnique({
+    where: { stripeSubscriptionId: subscription.id },
+  });
+
+  if (!sub) return;
+
+  await prisma.subscription.update({
+    where: { id: sub.id },
+    data: { status: 'canceled' },
+  });
+
+  logger.info('Subscription canceled', { userId: sub.userId });
+}
+
+export async function handlePaymentFailed(invoice: Stripe.Invoice): Promise<void> {
+  const customerId = invoice.customer as string;
+  const sub = await prisma.subscription.findUnique({
+    where: { stripeCustomerId: customerId },
+  });
+
+  if (!sub) return;
+
+  await prisma.subscription.update({
+    where: { id: sub.id },
+    data: { status: 'past_due' },
+  });
+
+  logger.warn('Payment failed', { userId: sub.userId, customerId });
+}

package/src/lib/utils/api-response.ts

@@ -0,0 +1,85 @@
+import { NextResponse } from 'next/server';
+import { isAppError, toAppError } from './errors';
+
+type SuccessResponse<T> = {
+  success: true;
+  data: T;
+};
+
+type ErrorResponse = {
+  success: false;
+  error: {
+    message: string;
+    code: string;
+    details?: Record<string, unknown>;
+  };
+};
+
+type PaginatedResponse<T> = SuccessResponse<{
+  items: T[];
+  pagination: {
+    total: number;
+    page: number;
+    pageSize: number;
+    hasMore: boolean;
+  };
+}>;
+
+export type ApiResponse<T = unknown> = SuccessResponse<T> | ErrorResponse;
+
+export function success<T>(data: T, status = 200): NextResponse<SuccessResponse<T>> {
+  return NextResponse.json({ success: true, data }, { status });
+}
+
+export function error(err: unknown): NextResponse<ErrorResponse> {
+  const appError = toAppError(err);
+  return NextResponse.json(
+    {
+      success: false,
+      error: {
+        message: appError.message,
+        code: appError.code,
+        details: appError.details,
+      },
+    },
+    { status: appError.statusCode },
+  );
+}
+
+export function paginated<T>(
+  items: T[],
+  total: number,
+  page: number,
+  pageSize: number,
+): NextResponse<PaginatedResponse<T>> {
+  return NextResponse.json({
+    success: true,
+    data: {
+      items,
+      pagination: {
+        total,
+        page,
+        pageSize,
+        hasMore: page * pageSize < total,
+      },
+    },
+  });
+}
+
+export function noContent(): NextResponse {
+  return new NextResponse(null, { status: 204 });
+}
+
+export function handleApiError(handlerOrError: (() => Promise<NextResponse>) | unknown): Promise<NextResponse> | NextResponse<ErrorResponse> {
+  if (typeof handlerOrError === 'function') {
+    return handlerOrError().catch((err: unknown) => {
+      if (isAppError(err)) return error(err);
+      console.error('Unhandled API error:', err);
+      return error(err);
+    });
+  }
+  // Direct error value
+  if (isAppError(handlerOrError)) return error(handlerOrError);
+  console.error('Unhandled API error:', handlerOrError);
+  return error(handlerOrError);
+}

package/src/lib/utils/errors.ts

@@ -0,0 +1,73 @@
+export class AppError extends Error {
+  constructor(
+    message: string,
+    public readonly statusCode: number = 500,
+    public readonly code: string = 'INTERNAL_ERROR',
+    public readonly details?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = 'AppError';
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(resource: string, id?: string) {
+    super(
+      id ? `${resource} with id '${id}' not found` : `${resource} not found`,
+      404,
+      'NOT_FOUND',
+    );
+    this.name = 'NotFoundError';
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(message = 'Authentication required') {
+    super(message, 401, 'UNAUTHORIZED');
+    this.name = 'UnauthorizedError';
+  }
+}
+
+export class ForbiddenError extends AppError {
+  constructor(message = 'You do not have permission to perform this action') {
+    super(message, 403, 'FORBIDDEN');
+    this.name = 'ForbiddenError';
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(message: string, public readonly fields?: Record<string, string[]>) {
+    super(message, 400, 'VALIDATION_ERROR', fields ? { fields } : undefined);
+    this.name = 'ValidationError';
+  }
+}
+
+export class RateLimitError extends AppError {
+  constructor(public readonly retryAfter: number = 60) {
+    super(
+      `Rate limit exceeded. Try again in ${retryAfter} seconds.`,
+      429,
+      'RATE_LIMIT_EXCEEDED',
+    );
+    this.name = 'RateLimitError';
+  }
+}
+
+export class BillingError extends AppError {
+  constructor(message: string) {
+    super(message, 402, 'BILLING_ERROR');
+    this.name = 'BillingError';
+  }
+}
+
+export function isAppError(error: unknown): error is AppError {
+  return error instanceof AppError;
+}
+
+export function toAppError(error: unknown): AppError {
+  if (isAppError(error)) return error;
+  if (error instanceof Error) {
+    return new AppError(error.message, 500, 'INTERNAL_ERROR');
+  }
+  return new AppError('An unexpected error occurred', 500, 'INTERNAL_ERROR');
+}

package/src/lib/utils/helpers.ts

@@ -0,0 +1,50 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+export function formatCurrency(amount: number, currency = 'USD'): string {
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency,
+  }).format(amount);
+}
+
+export function formatNumber(num: number): string {
+  return new Intl.NumberFormat('en-US').format(num);
+}
+
+export function formatRelativeTime(date: Date | string): string {
+  const d = typeof date === 'string' ? new Date(date) : date;
+  const now = new Date();
+  const diffMs = now.getTime() - d.getTime();
+  const diffSecs = Math.floor(diffMs / 1000);
+  const diffMins = Math.floor(diffSecs / 60);
+  const diffHours = Math.floor(diffMins / 60);
+  const diffDays = Math.floor(diffHours / 24);
+
+  if (diffSecs < 60) return 'just now';
+  if (diffMins < 60) return `${diffMins}m ago`;
+  if (diffHours < 24) return `${diffHours}h ago`;
+  if (diffDays < 30) return `${diffDays}d ago`;
+  return d.toLocaleDateString();
+}
+
+export function truncate(str: string, maxLength: number): string {
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength - 3) + '...';
+}
+
+export function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+export function slugify(str: string): string {
+  return str
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/[\s_-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}

package/src/lib/utils/id.ts

@@ -0,0 +1,21 @@
+import { nanoid } from 'nanoid';
+
+export function generateId(size = 21): string {
+  return nanoid(size);
+}
+
+export function generateApiKey(): { key: string; prefix: string; hashed: string } {
+  const prefix = 'ak';
+  const secret = nanoid(32);
+  const key = `${prefix}_${secret}`;
+  const displayPrefix = key.slice(0, 8);
+  // In production, hash with bcrypt. For starter kit, use the key directly.
+  return { key, prefix: displayPrefix, hashed: key };
+}
+
+export function generateChatTitle(message: string): string {
+  const maxLen = 50;
+  const cleaned = message.replace(/\n/g, ' ').trim();
+  if (cleaned.length <= maxLen) return cleaned;
+  return cleaned.slice(0, maxLen - 3) + '...';
+}

package/src/lib/utils/logger.ts

@@ -0,0 +1,38 @@
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+const currentLevel: LogLevel = (process.env.LOG_LEVEL as LogLevel) ?? 'info';
+
+function shouldLog(level: LogLevel): boolean {
+  return LOG_LEVELS[level] >= LOG_LEVELS[currentLevel];
+}
+
+function formatMessage(level: LogLevel, message: string, meta?: Record<string, unknown>): string {
+  const timestamp = new Date().toISOString();
+  const base = `[${timestamp}] [${level.toUpperCase()}] ${message}`;
+  if (meta && Object.keys(meta).length > 0) {
+    return `${base} ${JSON.stringify(meta)}`;
+  }
+  return base;
+}
+
+export const logger = {
+  debug(message: string, meta?: Record<string, unknown>) {
+    if (shouldLog('debug')) console.debug(formatMessage('debug', message, meta));
+  },
+  info(message: string, meta?: Record<string, unknown>) {
+    if (shouldLog('info')) console.info(formatMessage('info', message, meta));
+  },
+  warn(message: string, meta?: Record<string, unknown>) {
+    if (shouldLog('warn')) console.warn(formatMessage('warn', message, meta));
+  },
+  error(message: string, meta?: Record<string, unknown>) {
+    if (shouldLog('error')) console.error(formatMessage('error', message, meta));
+  },
+};

package/src/lib/utils/validation.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+
+export const createAgentSchema = z.object({
+  name: z.string().min(1, 'Name is required').max(100, 'Name too long'),
+  description: z.string().max(500, 'Description too long').optional(),
+  systemPrompt: z.string().min(1, 'System prompt is required').max(10000, 'System prompt too long'),
+  model: z.string().min(1, 'Model is required').default('gpt-4o'),
+  temperature: z.number().min(0).max(2).default(0.7),
+  maxTokens: z.number().int().min(1).max(128000).default(4096),
+  tools: z.array(z.string()).default([]),
+  isPublic: z.boolean().default(false),
+});
+
+export const updateAgentSchema = z.object({
+  name: z.string().min(1).max(100).optional(),
+  description: z.string().max(500).optional(),
+  systemPrompt: z.string().min(1).max(10000).optional(),
+  model: z.string().min(1).optional(),
+  temperature: z.number().min(0).max(2).optional(),
+  maxTokens: z.number().int().min(1).max(128000).optional(),
+  tools: z.array(z.string()).optional(),
+  isPublic: z.boolean().optional(),
+});
+
+export const chatMessageSchema = z.object({
+  message: z.string().min(1, 'Message is required').max(50000, 'Message too long'),
+  chatId: z.string().optional(),
+});
+
+export const createApiKeySchema = z.object({
+  name: z.string().min(1, 'Name is required').max(50, 'Name too long'),
+});
+
+export const paginationSchema = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  pageSize: z.coerce.number().int().min(1).max(100).default(20),
+  search: z.string().optional(),
+});
+
+export type CreateAgentInput = z.infer<typeof createAgentSchema>;
+export type UpdateAgentInput = z.infer<typeof updateAgentSchema>;
+export type ChatMessageInput = z.infer<typeof chatMessageSchema>;
+export type CreateApiKeyInput = z.infer<typeof createApiKeySchema>;
+export type PaginationInput = z.infer<typeof paginationSchema>;

package/src/middleware.ts

@@ -0,0 +1,13 @@
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+import { authMiddleware } from '@/lib/auth/middleware';
+
+export async function middleware(req: NextRequest) {
+  return authMiddleware(req);
+}
+
+export const config = {
+  matcher: [
+    '/((?!_next/static|_next/image|favicon.ico|public).*)',
+  ],
+};

package/src/types/agent.ts

@@ -0,0 +1,31 @@
+export interface Agent {
+  id: string;
+  name: string;
+  description: string;
+  systemPrompt: string;
+  model: string;
+  temperature: number;
+  maxTokens: number;
+  tools: string[];
+  isPublic: boolean;
+  userId: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface AgentFormData {
+  name: string;
+  description?: string;
+  systemPrompt: string;
+  model: string;
+  temperature?: number;
+  maxTokens?: number;
+  tools?: string[];
+  isPublic?: boolean;
+}
+
+export type AgentWithStats = Agent & {
+  chatCount: number;
+  messageCount: number;
+  lastUsed: string | null;
+};

package/src/types/api.ts

@@ -0,0 +1,38 @@
+export interface ApiResponse<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: {
+    code: string;
+    message: string;
+    details?: unknown;
+  };
+}
+
+export interface PaginatedResponse<T> extends ApiResponse<T[]> {
+  pagination: {
+    page: number;
+    pageSize: number;
+    total: number;
+    totalPages: number;
+  };
+}
+
+export interface ApiKey {
+  id: string;
+  name: string;
+  prefix: string;
+  key: string; // Only present on creation
+  lastUsed: string | null;
+  createdAt: string;
+}
+
+export interface HealthCheck {
+  status: 'ok' | 'degraded' | 'down';
+  timestamp: string;
+  version: string;
+  services: {
+    database: 'ok' | 'down';
+    redis: 'ok' | 'down' | 'not_configured';
+    stripe: 'ok' | 'down' | 'not_configured';
+  };
+}

package/src/types/billing.ts

@@ -0,0 +1,35 @@
+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 interface Subscription {
+  id: string;
+  userId: string;
+  stripeCustomerId: string;
+  stripePriceId: string;
+  stripeSubscriptionId: string;
+  status: 'active' | 'past_due' | 'canceled' | 'trialing' | 'incomplete';
+  currentPeriodStart: string;
+  currentPeriodEnd: string;
+  cancelAtPeriodEnd: boolean;
+}
+
+export interface UsageSummary {
+  messages: number;
+  toolCalls: number;
+  inputTokens: number;
+  outputTokens: number;
+}

package/src/types/chat.ts

@@ -0,0 +1,30 @@
+export interface Chat {
+  id: string;
+  agentId: string;
+  userId: string;
+  title: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface Message {
+  id: string;
+  chatId: string;
+  role: 'user' | 'assistant' | 'system' | 'tool';
+  content: string;
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+}
+
+export interface ChatWithMessages extends Chat {
+  messages: Message[];
+  _count: { messages: number };
+}
+
+export type StreamEventType = 'text' | 'tool_call' | 'tool_result' | 'error' | 'done';
+
+export interface StreamEvent {
+  type: StreamEventType;
+  content: string;
+  metadata?: Record<string, unknown>;
+}