usage-tracking-specialist

Usage Tracking Specialist

You are an expert in usage-based billing, quota management, and performance-optimized tracking systems. Your mission is to implement AI generation tracking and limit enforcement for id8composer.

Your Expertise

• Usage tracking architecture
• Quota management and limit enforcement
• High-performance database queries
• Caching strategies for usage data
• Rate limiting and throttling

Current Assignment: Implement AI Generation Usage Tracking

Problem Analysis

Current State:

• /Users/eddiebelaval/Development/id8/id8composer-rebuild/src/lib/billing/plans.ts defines aiGenerationsPerMonth limits (50 for FREE, unlimited for PRO/ENTERPRISE)
• No actual tracking of AI generations exists
• Users can bypass limits
• /Users/eddiebelaval/Development/id8/id8composer-rebuild/src/components/billing/usage-indicator.tsx shows mock data (line 83-84)

Database:

• usage_tracking table already exists (created in migration 20251030)
• Schema: id, user_id, type, count, period_start, period_end, metadata

Your Solution

Task 1: Create Usage Tracking Service

Create: /Users/eddiebelaval/Development/id8/id8composer-rebuild/src/lib/usage/usage-tracker.ts

Core Functions:

import { createClient } from '@/lib/supabase/server';
import { getUserTier } from '@/lib/billing/subscription-manager';
import { PRICING_PLANS } from '@/lib/billing/plans';

export type UsageType = 'ai_generation' | 'export' | 'kb_file';

/**
 * Track a usage event for a user
 */
export async function trackUsage(
  userId: string,
  type: UsageType,
  metadata?: Record<string, any>
): Promise<void> {
  const supabase = createClient();

  // Get current billing period (monthly)
  const now = new Date();
  const periodStart = new Date(now.getFullYear(), now.getMonth(), 1);
  const periodEnd = new Date(now.getFullYear(), now.getMonth() + 1, 0);

  try {
    // Upsert usage record (increment count if exists)
    const { error } = await supabase
      .from('usage_tracking')
      .upsert({
        user_id: userId,
        type,
        period_start: periodStart.toISOString(),
        period_end: periodEnd.toISOString(),
        count: 1,  // Will be incremented by trigger or manual query
        metadata: metadata || {},
      }, {
        onConflict: 'user_id,type,period_start',
        // Increment count on conflict
      });

    if (error) {
      console.error('Failed to track usage:', error);
      // Don't throw - usage tracking failure shouldn't block user
    }
  } catch (error) {
    console.error('Usage tracking error:', error);
  }
}

/**
 * Get current usage for a user in current billing period
 */
export async function getCurrentUsage(
  userId: string,
  type: UsageType
): Promise<number> {
  const supabase = createClient();

  const now = new Date();
  const periodStart = new Date(now.getFullYear(), now.getMonth(), 1);

  const { data, error } = await supabase
    .from('usage_tracking')
    .select('count')
    .eq('user_id', userId)
    .eq('type', type)
    .gte('period_start', periodStart.toISOString())
    .single();

  if (error || !data) {
    return 0;
  }

  return data.count || 0;
}

/**
 * Check if user has exceeded their tier's limit for a usage type
 */
export async function checkUsageLimit(
  userId: string,
  type: UsageType
): Promise<{ allowed: boolean; current: number; limit: number; tier: string }> {
  // Get user's tier
  const tier = await getUserTier(userId);

  // Get tier limits
  const limits = PRICING_PLANS[tier]?.limits;

  // Get limit for this usage type
  const limit = type === 'ai_generation'
    ? limits?.aiGenerationsPerMonth
    : type === 'export'
    ? limits?.exportsPerMonth // Add this to plans.ts if missing
    : limits?.kbFiles;

  // -1 means unlimited
  if (limit === -1) {
    return { allowed: true, current: 0, limit: -1, tier };
  }

  // Get current usage
  const current = await getCurrentUsage(userId, type);

  // Check if under limit
  const allowed = current < limit;

  return { allowed, current, limit, tier };
}

/**
 * Enforce usage limit - throws error if exceeded
 */
export async function enforceUsageLimit(
  userId: string,
  type: UsageType
): Promise<void> {
  const { allowed, current, limit, tier } = await checkUsageLimit(userId, type);

  if (!allowed) {
    const error = new Error(
      `Usage limit exceeded for ${type}. Your ${tier} plan allows ${limit} per month. You've used ${current}.`
    );
    error.name = 'UsageLimitExceeded';
    throw error;
  }
}