Aeion Tax — Zero-API-Fee Tax Calculation Engine

Five postal code matching strategies:

```typescript // 1. EXACT — single postal code { postalCodeType: "exact", postalCode: "90210", // Matches ONLY 90210 }

// 2. PREFIX — wildcard start (all ZIPs in a region) { postalCodeType: "prefix", postalCodePrefix: "902", // Matches 90210, 90211, 90212... }

// 3. RANGE — numeric range (handle split ZIP codes) { postalCodeType: "range", postalCodeRangeStart: "10001", postalCodeRangeEnd: "10099", // Matches 10001-10099 }

// 4. LIST — specific codes (handle non-contiguous areas) { postalCodeType: "list", postalCodeList: ["94102", "94103", "94107", "94108", "94110", "94114"], }

// 5. REGEX — complex patterns (with ReDoS protection) { postalCodeType: "regex", postalCodeRegex: "^[0-9]{5}(-[0-9]{4})?$", // US ZIP or ZIP+4 } ```

ReDoS protection (regex patterns capped at 100 characters):

```typescript // Dangerous patterns are BLOCKED: ❌ /\(\.\\)\+/ // (.)+ — exponential backtracking ❌ /\[\^[^\]]\]\+\+/ // [^...]++ — catastrophic ❌ /\(\?=.\)\*/ // Lookahead + quantifier

✅ /\b\d{5}\b/ // Simple — allowed ✅ /^90[0-9]{3}$/ // Prefix pattern — allowed ```

Jurisdiction specificity ranking:

``` Postal code match: score +8 City match: score +4 County match: score +2 State match: score +1

→ Most specific jurisdiction wins → Rate priority field as tiebreaker ```

Tax classes let you handle products differently in different places:

```typescript // Tax class: "clothing" { code: "clothing", name: "Apparel - Clothing", defaultTreatment: "taxable", jurisdictionRules: [ { country: "US", state: "TX", // Texas: clothing exempt treatment: "exempt", effectiveFrom: "2024-01-01", effectiveUntil: "2024-12-31", }, { country: "US", state: "PA", // Pennsylvania: $0-100 exempt, above taxed treatment: "partial", exemptionAmount: 10000, // $100 in cents }, { country: "US", state: "MN", // Minnesota: clothing exempt Nov-Dec only treatment: "seasonal", startMonth: 11, startDay: 1, endMonth: 12, endDay: 31, }, ], }

// Product assignment in commerce: { name: "Premium T-Shirt", sku: "TSHIRT-001", price: 2999, // $29.99 in cents taxClass: "clothing", }

// At checkout in Austin, TX → $0 tax (clothing exempt) // At checkout in Philadelphia, PA → $0 on first $100, $29.99 taxed above // At checkout in Minneapolis, MN in November → $0 tax (seasonal holiday) // At checkout in San Francisco, CA → full state+city tax applied ```

Class overrides in rate definitions:

```typescript // Rate that EXCLUDES a specific class { name: "CA State Tax", rate: 7.25, appliesToAllProducts: false, excludeProductTaxClassIds: ["clothing", "groceries", "prescription"], }

// Rate that INCLUDES only specific classes { name: "Digital Goods Surtax", rate: 3.0, appliesToAllProducts: false, productTaxClassIds: ["digital", "software", "streaming"], } ```

How exemption certificates work:

```typescript // Customer has exemption on file: { id: "exemp_001", customerId: "cust_12345", customerName: "Acme Wholesale LLC", exemptionType: "resale", exemptFromAll: true, // Full exemption // OR for partial: isPartialExemption: true, exemptionPercentage: 75, // 75% exempt, 25% taxed // OR maxExemptAmount: 100000, // First $1,000 exempt

scopeType: "specific_states", // Only in these states: exemptStates: ["TX", "FL", "NV"],

// OR scopeType: "specific_countries", exemptCountries: ["US"],

certificateNumber: "RESALE-TX-2026-001234", documentUrl: "https://...", // PDF of actual certificate expiresAt: "2027-05-11", neverExpires: false, status: "active", } ```

Exemption check at checkout:

```typescript calculateTax({ items: [...], shippingAddress: { country: "US", state: "TX", postalCode: "78701" }, customerId: "cust_12345", });

// → Checks the customer's exemption certificates for an active match // → Acme Wholesale has an active Texas resale certificate on file // → Full exemption applied → $0 tax // → Adjustment logged with a reference to the exemption for audit trail ```

Compound tax (tax on tax): California adds city tax on top of state tax:

```typescript // CA State Tax — base rate { name: "CA State", rate: 7.25, isCompound: false }

// Los Angeles County — compounds on state tax { name: "LA County", rate: 2.25, isCompound: true } // → Applied to: subtotal + state tax = $100 + $7.25 = $107.25 // → County tax: $107.25 × 2.25% = $2.41

// Los Angeles City — compounds on county tax { name: "LA City", rate: 1.50, isCompound: true } // → Applied to: subtotal + state + county = $100 + $7.25 + $2.41 = $109.66 // → City tax: $109.66 × 1.50% = $1.64

// Total: $7.25 + $2.41 + $1.64 = $11.30 on $100 // vs simple calculation: ($100 × 11%) = $11.00 // Compound math: $0.30 more — legally correct ```

Inclusive tax (VAT-style): Price already includes tax:

```typescript // UK VAT — price is gross, need net { name: "UK VAT", rate: 20.0, isInclusive: true, // Price already includes tax }

// $120 product with isInclusive=true // → Net amount: $120 / 1.20 = $100 // → Tax: $20 // → Effective rate shown: 20.00% ```

Order value thresholds:

```typescript // France reduced VAT on books under €17 { name: "FR Reduced VAT (Books)", rate: 5.5, appliesToAllProducts: false, productTaxClassIds: ["books"], maxOrderValue: 1700, // €17 in cents }

{ name: "FR Standard VAT (Books > €17)", rate: 20.0, appliesToAllProducts: false, productTaxClassIds: ["books"], minOrderValue: 1701, // Above €17 } ```