feat: Add endpoints to convert stripe subscription currencies (#715)

* feat: Add endpoints to convert stripe subscriptions

* chore: Fix subscription currency conversion not working

* fix: Failing tests

Author: sashko9807

apps/api/src/common/money.spec.ts

@@ -0,0 +1,136 @@
+import { BGN_TO_EUR_RATE, toMoney, eurToBgn, bgnToEur, getFixedExchangeRate } from './money'
+
+describe('money utilities', () => {
+  describe('BGN_TO_EUR_RATE', () => {
+    it('should be the fixed BGN to EUR rate', () => {
+      expect(BGN_TO_EUR_RATE).toBe(1.95583)
+    })
+  })
+
+  describe('toMoney', () => {
+    it('should convert number to cents', () => {
+      expect(toMoney(160.2)).toBe(16020)
+    })
+
+    it('should convert string to cents', () => {
+      expect(toMoney('160.2')).toBe(16020)
+    })
+
+    it('should handle whole numbers', () => {
+      expect(toMoney(100)).toBe(10000)
+    })
+
+    it('should handle zero', () => {
+      expect(toMoney(0)).toBe(0)
+    })
+
+    it('should round floating point precision issues', () => {
+      // 0.1 + 0.2 = 0.30000000000000004 in JavaScript
+      expect(toMoney(0.1 + 0.2)).toBe(30)
+    })
+  })
+
+  describe('eurToBgn', () => {
+    it('should convert EUR to BGN using the fixed rate', () => {
+      const result = eurToBgn(100)
+      expect(result).toBeCloseTo(195.583, 3)
+    })
+
+    it('should handle amount in cents', () => {
+      // 10000 cents = 100 EUR -> should give BGN amount
+      const result = eurToBgn(10000, true)
+      expect(result).toBeCloseTo(195.583, 3)
+    })
+
+    it('should handle zero', () => {
+      expect(eurToBgn(0)).toBe(0)
+    })
+
+    it('should handle decimal amounts', () => {
+      const result = eurToBgn(50.5)
+      expect(result).toBeCloseTo(98.769415, 3)
+    })
+  })
+
+  describe('bgnToEur', () => {
+    it('should convert BGN to EUR using the fixed rate', () => {
+      const result = bgnToEur(195.583)
+      expect(result).toBeCloseTo(100, 3)
+    })
+
+    it('should handle amount in cents and round result', () => {
+      // 19558 stotinki (BGN cents) should convert to EUR cents
+      const result = bgnToEur(19558, true)
+      // 19558 / 1.95583 ≈ 9999.95 -> rounds to 10000
+      expect(result).toBe(10000)
+    })
+
+    it('should handle zero', () => {
+      expect(bgnToEur(0)).toBe(0)
+    })
+
+    it('should handle decimal amounts', () => {
+      const result = bgnToEur(100)
+      expect(result).toBeCloseTo(51.129, 3)
+    })
+
+    it('should properly round cents conversion', () => {
+      // Test that 1000 BGN cents converts correctly
+      const result = bgnToEur(1000, true)
+      // 1000 / 1.95583 ≈ 511.29 -> rounds to 511
+      expect(result).toBe(511)
+    })
+
+    it('should be the inverse of eurToBgn', () => {
+      const originalEur = 100
+      const bgn = eurToBgn(originalEur)
+      const backToEur = bgnToEur(bgn)
+      expect(backToEur).toBeCloseTo(originalEur, 10)
+    })
+  })
+
+  describe('getFixedExchangeRate', () => {
+    it('should return the BGN to EUR rate', () => {
+      const rate = getFixedExchangeRate('BGN', 'EUR')
+      expect(rate).toBeDefined()
+      expect(rate).toBeCloseTo(1 / BGN_TO_EUR_RATE, 10)
+      expect(rate).toBeCloseTo(0.5113, 4)
+    })
+
+    it('should return the EUR to BGN rate', () => {
+      const rate = getFixedExchangeRate('EUR', 'BGN')
+      expect(rate).toBeDefined()
+      expect(rate).toBe(BGN_TO_EUR_RATE)
+    })
+
+    it('should return undefined for unknown currency pairs', () => {
+      expect(getFixedExchangeRate('USD', 'EUR')).toBeUndefined()
+      expect(getFixedExchangeRate('GBP', 'BGN')).toBeUndefined()
+      expect(getFixedExchangeRate('BGN', 'USD')).toBeUndefined()
+    })
+
+    it('should return undefined for same currency', () => {
+      expect(getFixedExchangeRate('EUR', 'EUR')).toBeUndefined()
+      expect(getFixedExchangeRate('BGN', 'BGN')).toBeUndefined()
+    })
+
+    it('should be case sensitive', () => {
+      expect(getFixedExchangeRate('bgn', 'eur')).toBeUndefined()
+      expect(getFixedExchangeRate('Bgn', 'Eur')).toBeUndefined()
+    })
+
+    it('BGN_EUR rate should allow correct conversion', () => {
+      const rate = getFixedExchangeRate('BGN', 'EUR')!
+      const bgnAmount = 195.583
+      const eurAmount = bgnAmount * rate
+      expect(eurAmount).toBeCloseTo(100, 3)
+    })
+
+    it('EUR_BGN rate should allow correct conversion', () => {
+      const rate = getFixedExchangeRate('EUR', 'BGN')!
+      const eurAmount = 100
+      const bgnAmount = eurAmount * rate
+      expect(bgnAmount).toBeCloseTo(195.583, 3)
+    })
+  })
+})

apps/api/src/common/money.ts

@@ -26,3 +26,37 @@ export function eurToBgn(eurAmount: number, isInCents = false): number {
   const amountInEur = isInCents ? eurAmount / 100 : eurAmount
   return amountInEur * BGN_TO_EUR_RATE
 }
+
+/**
+ * Converts BGN amount to EUR amount using the fixed exchange rate
+ * @param bgnAmount - Amount in BGN (can be in cents or regular units)
+ * @param isInCents - Whether the input amount is in cents (default: false)
+ * @returns Amount in EUR (in the same unit as input - cents or regular)
+ */
+export function bgnToEur(bgnAmount: number, isInCents = false): number {
+  // When converting BGN to EUR, we divide by the rate since 1 EUR = 1.95583 BGN
+  if (isInCents) {
+    // For cents, we need to maintain precision and round
+    return Math.round(bgnAmount / BGN_TO_EUR_RATE)
+  }
+  return bgnAmount / BGN_TO_EUR_RATE
+}
+
+/**
+ * Gets the fixed exchange rate for a currency pair
+ * Returns undefined if no fixed rate exists for the pair
+ * @param sourceCurrency - Source currency code (e.g., 'BGN')
+ * @param targetCurrency - Target currency code (e.g., 'EUR')
+ * @returns The exchange rate to multiply by, or undefined if no fixed rate exists
+ */
+export function getFixedExchangeRate(
+  sourceCurrency: string,
+  targetCurrency: string,
+): number | undefined {
+  const rateKey = `${sourceCurrency}_${targetCurrency}`
+  const fixedRates: Record<string, number> = {
+    BGN_EUR: 1 / BGN_TO_EUR_RATE, // ~0.5113 (1 BGN = 0.5113 EUR)
+    EUR_BGN: BGN_TO_EUR_RATE, // 1.95583 (1 EUR = 1.95583 BGN)
+  }
+  return fixedRates[rateKey]
+}

apps/api/src/stripe/dto/currency-conversion.dto.ts

@@ -0,0 +1,181 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger'
+import { Currency } from '@prisma/client'
+import { Expose } from 'class-transformer'
+import { IsBoolean, IsEnum, IsNumber, IsOptional, IsString } from 'class-validator'
+
+/**
+ * Request DTO for bulk currency conversion of all subscriptions
+ * Designed to be generic for future currency conversions (e.g., BGN to EUR)
+ */
+export class ConvertSubscriptionsCurrencyDto {
+  @ApiProperty({ enum: Currency, description: 'Source currency to convert from' })
+  @Expose()
+  @IsEnum(Currency)
+  sourceCurrency: Currency
+
+  @ApiProperty({ enum: Currency, description: 'Target currency to convert to' })
+  @Expose()
+  @IsEnum(Currency)
+  targetCurrency: Currency
+
+  @ApiPropertyOptional({
+    description:
+      'Custom exchange rate. If not provided, uses fixed rate for known pairs (e.g., BGN/EUR)',
+  })
+  @Expose()
+  @IsNumber()
+  @IsOptional()
+  exchangeRate?: number
+
+  @ApiPropertyOptional({
+    description: 'Run in dry-run mode without making actual changes',
+    default: false,
+  })
+  @Expose()
+  @IsBoolean()
+  @IsOptional()
+  dryRun?: boolean
+
+  @ApiPropertyOptional({
+    description: 'Batch size for processing subscriptions (for pagination)',
+    default: 100,
+  })
+  @Expose()
+  @IsNumber()
+  @IsOptional()
+  batchSize?: number
+
+  @ApiPropertyOptional({
+    description:
+      'Delay in milliseconds between each conversion to respect Stripe rate limits. ' +
+      'Stripe allows ~100 requests/second in live mode, ~25/second in test mode.',
+    default: 100,
+  })
+  @Expose()
+  @IsNumber()
+  @IsOptional()
+  delayMs?: number
+}
+
+/**
+ * Request DTO for single subscription currency conversion
+ */
+export class ConvertSingleSubscriptionCurrencyDto {
+  @ApiProperty({ enum: Currency, description: 'Target currency to convert to' })
+  @Expose()
+  @IsEnum(Currency)
+  targetCurrency: Currency
+
+  @ApiPropertyOptional({
+    description: 'Custom exchange rate. If not provided, uses fixed rate for known pairs',
+  })
+  @Expose()
+  @IsNumber()
+  @IsOptional()
+  exchangeRate?: number
+
+  @ApiPropertyOptional({
+    description: 'Run in dry-run mode without making actual changes',
+    default: false,
+  })
+  @Expose()
+  @IsBoolean()
+  @IsOptional()
+  dryRun?: boolean
+}
+
+/**
+ * Individual subscription conversion result
+ */
+export class SubscriptionConversionResultDto {
+  @ApiProperty({ description: 'Stripe subscription ID' })
+  @Expose()
+  subscriptionId: string
+
+  @ApiProperty({ description: 'Original amount in cents' })
+  @Expose()
+  originalAmount: number
+
+  @ApiProperty({ description: 'Converted amount in cents' })
+  @Expose()
+  convertedAmount: number
+
+  @ApiProperty({ enum: Currency, description: 'Original currency before conversion' })
+  @Expose()
+  originalCurrency: string
+
+  @ApiProperty({ enum: Currency, description: 'Target currency after conversion' })
+  @Expose()
+  targetCurrency: Currency
+
+  @ApiProperty({ description: 'Whether the conversion was successful' })
+  @Expose()
+  success: boolean
+
+  @ApiPropertyOptional({ description: 'Error message if conversion failed' })
+  @Expose()
+  @IsString()
+  @IsOptional()
+  errorMessage?: string
+
+  @ApiPropertyOptional({ description: 'Campaign ID from subscription metadata' })
+  @Expose()
+  @IsString()
+  @IsOptional()
+  campaignId?: string
+}
+
+/**
+ * Response DTO for bulk currency conversion operation
+ */
+export class ConvertSubscriptionsCurrencyResponseDto {
+  @ApiProperty({ description: 'Total subscriptions processed' })
+  @Expose()
+  totalFound: number
+
+  @ApiProperty({ description: 'Number of successfully converted subscriptions' })
+  @Expose()
+  successCount: number
+
+  @ApiProperty({ description: 'Number of failed conversions' })
+  @Expose()
+  failedCount: number
+
+  @ApiProperty({
+    description:
+      'Number of subscriptions skipped (already in target currency or not matching source)',
+  })
+  @Expose()
+  skippedCount: number
+
+  @ApiProperty({ description: 'Exchange rate used for conversion' })
+  @Expose()
+  exchangeRate: number
+
+  @ApiProperty({ enum: Currency, description: 'Source currency' })
+  @Expose()
+  sourceCurrency: Currency
+
+  @ApiProperty({ enum: Currency, description: 'Target currency' })
+  @Expose()
+  targetCurrency: Currency
+
+  @ApiProperty({ description: 'Whether this was a dry run (no actual changes made)' })
+  @Expose()
+  dryRun: boolean
+
+  @ApiProperty({
+    type: [SubscriptionConversionResultDto],
+    description: 'Detailed results for each subscription',
+  })
+  @Expose()
+  results: SubscriptionConversionResultDto[]
+
+  @ApiProperty({ description: 'Timestamp when conversion started' })
+  @Expose()
+  startedAt: Date
+
+  @ApiProperty({ description: 'Timestamp when conversion completed' })
+  @Expose()
+  completedAt: Date
+}