Build a Tax Calculation Engine

// src/tax/engine.ts — Multi-jurisdiction tax calculation with exemptions and reporting
import { pool } from "../db";
import { Redis } from "ioredis";

const redis = new Redis(process.env.REDIS_URL!);

type TaxType = "sales_tax" | "vat" | "gst" | "none";

interface TaxResult {
  subtotal: number;
  taxAmount: number;
  total: number;
  effectiveRate: number;
  taxType: TaxType;
  jurisdiction: string;
  breakdown: Array<{
    name: string;
    rate: number;
    amount: number;
    jurisdiction: string;
  }>;
  exemptionApplied: boolean;
  reverseCharge: boolean;
}

interface TaxContext {
  sellerId: string;
  sellerCountry: string;
  sellerState?: string;
  buyerCountry: string;
  buyerState?: string;
  buyerCity?: string;
  buyerZip?: string;
  buyerIsBusinesss: boolean;
  buyerVatId?: string;
  productCategory: string;     // "saas", "digital_goods", "physical_goods", "consulting"
  amount: number;
  currency: string;
}

// US state tax rates (simplified — production would use a tax API or database)
const US_STATE_RATES: Record<string, number> = {
  CA: 0.0725, NY: 0.08, TX: 0.0625, FL: 0.06, WA: 0.065,
  IL: 0.0625, PA: 0.06, OH: 0.0575, GA: 0.04, NC: 0.0475,
  // ... all 50 states
};

// EU VAT rates
const EU_VAT_RATES: Record<string, number> = {
  DE: 0.19, FR: 0.20, IT: 0.22, ES: 0.21, NL: 0.21,
  BE: 0.21, AT: 0.20, PL: 0.23, SE: 0.25, DK: 0.25,
  FI: 0.24, IE: 0.23, PT: 0.23, CZ: 0.21, RO: 0.19,
  HU: 0.27, SK: 0.20, BG: 0.20, HR: 0.25, LT: 0.21,
  SI: 0.22, LV: 0.21, EE: 0.22, CY: 0.19, LU: 0.17,
  MT: 0.18, EL: 0.24,
};

// SaaS taxability by US state
const SAAS_TAXABLE_STATES = new Set([
  "TX", "NY", "PA", "WA", "CT", "DC", "HI", "IA", "KY",
  "MA", "MN", "MS", "NM", "OH", "RI", "SC", "SD", "TN", "UT", "WV",
]);

// Calculate tax for a transaction
export async function calculateTax(context: TaxContext): Promise<TaxResult> {
  const cacheKey = `tax:${context.buyerCountry}:${context.buyerState}:${context.productCategory}:${context.buyerIsBusinesss}`;
  const cached = await redis.get(cacheKey);

  let rate: number;
  let taxType: TaxType;
  let breakdown: TaxResult["breakdown"] = [];
  let reverseCharge = false;
  let exemptionApplied = false;

  // Determine jurisdiction and rate
  if (context.buyerCountry === "US") {
    ({ rate, taxType, breakdown, exemptionApplied } = calculateUSTax(context));
  } else if (EU_VAT_RATES[context.buyerCountry]) {
    ({ rate, taxType, breakdown, reverseCharge } = calculateEUVAT(context));
  } else if (context.buyerCountry === "AU") {
    rate = 0.10;
    taxType = "gst";
    breakdown = [{ name: "GST", rate: 0.10, amount: context.amount * 0.10, jurisdiction: "AU" }];
  } else if (context.buyerCountry === "CA") {
    rate = 0.05; // GST (simplified — provinces have additional PST/HST)
    taxType = "gst";
    breakdown = [{ name: "GST", rate: 0.05, amount: context.amount * 0.05, jurisdiction: "CA" }];
  } else {
    rate = 0;
    taxType = "none";
  }

  // Check exemption certificates
  if (context.buyerIsBusinesss && context.buyerVatId) {
    const exemptionValid = await validateExemption(context.buyerVatId, context.buyerCountry);
    if (exemptionValid) {
      exemptionApplied = true;
      if (context.buyerCountry !== context.sellerCountry) {
        rate = 0;
        reverseCharge = true;
        breakdown = [{ name: "Reverse Charge", rate: 0, amount: 0, jurisdiction: context.buyerCountry }];
      }
    }
  }

  const taxAmount = Math.round(context.amount * rate);

  const result: TaxResult = {
    subtotal: context.amount,
    taxAmount,
    total: context.amount + taxAmount,
    effectiveRate: rate,
    taxType,
    jurisdiction: `${context.buyerCountry}${context.buyerState ? `-${context.buyerState}` : ""}`,
    breakdown,
    exemptionApplied,
    reverseCharge,
  };

  // Cache rate for 24 hours
  await redis.setex(cacheKey, 86400, JSON.stringify({ rate, taxType }));

  return result;
}

function calculateUSTax(context: TaxContext): {
  rate: number; taxType: TaxType;
  breakdown: TaxResult["breakdown"]; exemptionApplied: boolean;
} {
  // Check nexus (do we have tax obligation in this state?)
  // For SaaS: economic nexus typically applies if revenue > $100K or 200+ transactions in a state
  const state = context.buyerState;
  if (!state) return { rate: 0, taxType: "none", breakdown: [], exemptionApplied: false };

  // Check if SaaS is taxable in this state
  if (context.productCategory === "saas" && !SAAS_TAXABLE_STATES.has(state)) {
    return { rate: 0, taxType: "none", breakdown: [], exemptionApplied: false };
  }

  const stateRate = US_STATE_RATES[state] || 0;
  if (stateRate === 0) return { rate: 0, taxType: "none", breakdown: [], exemptionApplied: false };

  return {
    rate: stateRate,
    taxType: "sales_tax",
    breakdown: [{ name: `${state} Sales Tax`, rate: stateRate, amount: Math.round(context.amount * stateRate), jurisdiction: `US-${state}` }],
    exemptionApplied: false,
  };
}

function calculateEUVAT(context: TaxContext): {
  rate: number; taxType: TaxType;
  breakdown: TaxResult["breakdown"]; reverseCharge: boolean;
} {
  const buyerRate = EU_VAT_RATES[context.buyerCountry] || 0;

  // B2B cross-border: reverse charge
  if (context.buyerIsBusinesss && context.buyerCountry !== context.sellerCountry) {
    return {
      rate: 0,
      taxType: "vat",
      breakdown: [{ name: "Reverse Charge VAT", rate: 0, amount: 0, jurisdiction: context.buyerCountry }],
      reverseCharge: true,
    };
  }

  // B2C or domestic B2B: charge destination country VAT
  return {
    rate: buyerRate,
    taxType: "vat",
    breakdown: [{ name: `${context.buyerCountry} VAT`, rate: buyerRate, amount: Math.round(context.amount * buyerRate), jurisdiction: context.buyerCountry }],
    reverseCharge: false,
  };
}

// Validate VAT ID via VIES API
async function validateExemption(vatId: string, country: string): Promise<boolean> {
  const cacheKey = `vat:valid:${vatId}`;
  const cached = await redis.get(cacheKey);
  if (cached !== null) return cached === "1";

  try {
    // In production: call EU VIES API
    const valid = vatId.length >= 8; // placeholder
    await redis.setex(cacheKey, 86400 * 7, valid ? "1" : "0");
    return valid;
  } catch {
    return false;
  }
}

// Generate tax report for a period
export async function generateTaxReport(period: string): Promise<{
  byJurisdiction: Array<{ jurisdiction: string; taxType: string; taxableAmount: number; taxCollected: number; transactionCount: number }>;
  totalTaxCollected: number;
  totalTransactions: number;
}> {
  const { rows } = await pool.query(
    `SELECT jurisdiction, tax_type,
            SUM(subtotal) as taxable_amount,
            SUM(tax_amount) as tax_collected,
            COUNT(*) as transaction_count
     FROM tax_records
     WHERE period = $1
     GROUP BY jurisdiction, tax_type
     ORDER BY tax_collected DESC`,
    [period]
  );

  return {
    byJurisdiction: rows.map((r) => ({
      jurisdiction: r.jurisdiction,
      taxType: r.tax_type,
      taxableAmount: parseFloat(r.taxable_amount),
      taxCollected: parseFloat(r.tax_collected),
      transactionCount: parseInt(r.transaction_count),
    })),
    totalTaxCollected: rows.reduce((s, r) => s + parseFloat(r.tax_collected), 0),
    totalTransactions: rows.reduce((s, r) => s + parseInt(r.transaction_count), 0),
  };
}