payment-kit 1.24.3 → 1.25.0

package/api/tests/libs/quote-service.spec.ts

@@ -0,0 +1,199 @@
+import { BN } from '@ocap/util';
+import crypto from 'crypto';
+
+describe('QuoteService', () => {
+  describe('Idempotency key generation', () => {
+    it('should generate consistent idempotency key for same params', () => {
+      const params = {
+        contextId: 'session_123',
+        priceId: 'price_456',
+        currencyId: 'currency_789',
+        quantity: 1,
+        baseAmount: '10.00',
+      };
+
+      const key1 = crypto
+        .createHash('sha256')
+        .update(`${params.contextId}:${params.priceId}:${params.currencyId}:${params.quantity}:${params.baseAmount}`)
+        .digest('hex')
+        .substring(0, 64);
+
+      const key2 = crypto
+        .createHash('sha256')
+        .update(`${params.contextId}:${params.priceId}:${params.currencyId}:${params.quantity}:${params.baseAmount}`)
+        .digest('hex')
+        .substring(0, 64);
+
+      expect(key1).toBe(key2);
+    });
+
+    it('should generate different keys for different quantities', () => {
+      const params1 = {
+        contextId: 'session_123',
+        priceId: 'price_456',
+        currencyId: 'currency_789',
+        quantity: 1,
+        baseAmount: '10.00',
+      };
+
+      const params2 = {
+        ...params1,
+        quantity: 2,
+        baseAmount: '20.00',
+      };
+
+      const key1 = crypto
+        .createHash('sha256')
+        .update(
+          `${params1.contextId}:${params1.priceId}:${params1.currencyId}:${params1.quantity}:${params1.baseAmount}`
+        )
+        .digest('hex')
+        .substring(0, 64);
+
+      const key2 = crypto
+        .createHash('sha256')
+        .update(
+          `${params2.contextId}:${params2.priceId}:${params2.currencyId}:${params2.quantity}:${params2.baseAmount}`
+        )
+        .digest('hex')
+        .substring(0, 64);
+
+      expect(key1).not.toBe(key2);
+    });
+  });
+
+  describe('Quote amount calculation', () => {
+    it('should correctly calculate quoted amount with ceiling', () => {
+      const baseAmount = 10; // $10 USD
+      const rate = 0.1; // 1 token = $0.1 USD
+      const decimals = 18;
+
+      // token_amount = base_usd / rate = 10 / 0.1 = 100 tokens
+      const tokenAmount = baseAmount / rate;
+      expect(tokenAmount).toBe(100);
+
+      // Using the same logic as QuoteService
+      const PRECISION_SCALE = 1e8;
+      const scaledNumerator = Math.floor(baseAmount * PRECISION_SCALE);
+      const scaledDenominator = Math.floor(rate * PRECISION_SCALE);
+      const numerator = new BN(scaledNumerator).mul(new BN(10).pow(new BN(decimals)));
+      const denominator = new BN(scaledDenominator);
+      const quotedAmount = numerator.add(denominator).sub(new BN(1)).div(denominator);
+
+      expect(quotedAmount.toString()).toBe('100000000000000000000');
+    });
+
+    it('should round up fractional token amounts', () => {
+      const baseAmount = 10.5; // $10.5 USD
+      const rate = 0.15; // 1 token = $0.15 USD
+      const decimals = 18;
+
+      // token_amount = 10.5 / 0.15 = 70
+      const tokenAmount = baseAmount / rate;
+      expect(tokenAmount).toBe(70);
+
+      const PRECISION_SCALE = 1e8;
+      const scaledNumerator = Math.floor(baseAmount * PRECISION_SCALE);
+      const scaledDenominator = Math.floor(rate * PRECISION_SCALE);
+      const numerator = new BN(scaledNumerator).mul(new BN(10).pow(new BN(decimals)));
+      const denominator = new BN(scaledDenominator);
+      const quotedAmount = numerator.add(denominator).sub(new BN(1)).div(denominator);
+
+      expect(quotedAmount.toString()).toBe('70000000000000000000');
+    });
+
+    it('should handle precision correctly with many decimals', () => {
+      const baseAmount = 100;
+      const rate = 0.123456789;
+      const decimals = 18;
+
+      const PRECISION_SCALE = 1e8;
+      const scaledNumerator = Math.floor(baseAmount * PRECISION_SCALE);
+      const scaledDenominator = Math.floor(rate * PRECISION_SCALE);
+      const numerator = new BN(scaledNumerator).mul(new BN(10).pow(new BN(decimals)));
+      const denominator = new BN(scaledDenominator);
+      const quotedAmount = numerator.add(denominator).sub(new BN(1)).div(denominator);
+
+      // Should ceil to ensure user pays enough
+      expect(quotedAmount.gt(new BN(0))).toBe(true);
+    });
+  });
+
+  describe('Quote expiration', () => {
+    it('should calculate correct expiration time', () => {
+      const now = Math.floor(Date.now() / 1000);
+      const lockDuration = 300; // 5 minutes
+      const expiresAt = now + lockDuration;
+
+      expect(expiresAt).toBeGreaterThan(now);
+      expect(expiresAt - now).toBe(lockDuration);
+    });
+
+    it('should use default lock duration of 300 seconds', () => {
+      const defaultLockDuration = 300;
+      const now = Math.floor(Date.now() / 1000);
+      const expiresAt = now + defaultLockDuration;
+
+      expect(expiresAt - now).toBe(300);
+    });
+  });
+
+  describe('Quote metadata structure', () => {
+    it('should include calculation details in metadata', () => {
+      const tokenAmount = '100.123456789';
+      const unitAmount = '100123456789000000000';
+
+      const metadata = {
+        calculation: {
+          token_amount_raw: tokenAmount,
+          unit_amount_raw: unitAmount,
+        },
+        rounding: {
+          mode: 'ceil',
+          token_decimals: 18,
+        },
+      };
+
+      expect(metadata.calculation.token_amount_raw).toBe(tokenAmount);
+      expect(metadata.calculation.unit_amount_raw).toBe(unitAmount);
+      expect(metadata.rounding.mode).toBe('ceil');
+    });
+
+    it('should include risk information in metadata', () => {
+      const metadata = {
+        risk: {
+          anomaly_detected: false,
+          degraded: false,
+          degraded_reason: null,
+        },
+      };
+
+      expect(metadata.risk.anomaly_detected).toBe(false);
+      expect(metadata.risk.degraded).toBe(false);
+    });
+  });
+
+  describe('Validation logic', () => {
+    it('should require either session_id or invoice_id', () => {
+      const params = {
+        price_id: 'price_123',
+        target_currency_id: 'currency_456',
+        quantity: 1,
+      };
+
+      // Neither session_id nor invoice_id provided
+      expect(params).not.toHaveProperty('session_id');
+      expect(params).not.toHaveProperty('invoice_id');
+    });
+
+    it('should validate dynamic pricing type', () => {
+      const price = {
+        pricing_type: 'fixed',
+        base_currency: 'USD',
+        base_amount: '10',
+      };
+
+      expect(price.pricing_type).not.toBe('dynamic');
+    });
+  });
+});

package/api/tests/libs/session.spec.ts

@@ -383,6 +383,470 @@ describe('getSubscriptionCreateSetup', () => {
         .unix()
     );
   });
+
+  describe('subscription authorization slippage protection', () => {
+    it('should NOT apply slippage for static pricing (backward compatibility)', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'fixed', // Static pricing
+          },
+          quantity: 1,
+        },
+      ];
+      const result = getSubscriptionCreateSetup(items as any, 'usd');
+      // Base: 1000, No slippage for static pricing
+      expect(result.amount.setup).toBe('1000');
+    });
+
+    it('should apply 0.5% slippage protection for dynamic pricing', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic', // Dynamic pricing
+          },
+          quantity: 1,
+        },
+      ];
+      const result = getSubscriptionCreateSetup(items as any, 'usd');
+      // Base: 1000, With 0.5% slippage: 1000 * 1.005 = 1005
+      expect(result.amount.setup).toBe('1005');
+    });
+
+    it('should apply slippage correctly with multiple quantities', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic',
+          },
+          quantity: 3,
+        },
+      ];
+      const result = getSubscriptionCreateSetup(items as any, 'usd');
+      // Base: 1000 * 3 = 3000, With 0.5% slippage: 3000 * 1.005 = 3015
+      expect(result.amount.setup).toBe('3015');
+    });
+
+    it('should apply slippage with mixed dynamic and one-time items', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic',
+          },
+          quantity: 1,
+        },
+        {
+          price: {
+            type: 'one_time',
+            currency_options: [{ currency_id: 'usd', unit_amount: '500' }],
+          },
+          quantity: 1,
+        },
+      ];
+      const result = getSubscriptionCreateSetup(items as any, 'usd');
+      // Base: 1000 (recurring) + 500 (one-time) = 1500
+      // With 0.5% slippage: 1500 * 1.005 = 1507
+      expect(result.amount.setup).toBe('1507');
+    });
+
+    it('should apply slippage with mixed dynamic and static recurring items', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic',
+          },
+          quantity: 1,
+        },
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '500' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'fixed', // Static pricing
+          },
+          quantity: 1,
+        },
+      ];
+      const result = getSubscriptionCreateSetup(items as any, 'usd');
+      // Base: 1000 (dynamic) + 500 (static) = 1500
+      // With 0.5% slippage (because at least one item is dynamic): 1500 * 1.005 = 1507
+      expect(result.amount.setup).toBe('1507');
+    });
+
+    it('should NOT apply slippage when setup amount is zero', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '0' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'metered' }, // Metered not included in setup
+            pricing_type: 'dynamic',
+          },
+          quantity: 1,
+        },
+      ];
+      const result = getSubscriptionCreateSetup(items as any, 'usd');
+      // Base: 0 (metered), No slippage applied
+      expect(result.amount.setup).toBe('0');
+    });
+
+    it('should handle large amounts with slippage correctly', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '10000000' }], // 10M
+            recurring: { interval: 'year', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic',
+          },
+          quantity: 1,
+        },
+      ];
+      const result = getSubscriptionCreateSetup(items as any, 'usd');
+      // Base: 10,000,000, With 0.5% slippage: 10,000,000 * 1.005 = 10,050,000
+      expect(result.amount.setup).toBe('10050000');
+    });
+
+    // Tests for custom slippage percentage parameter
+    it('should apply custom 5% slippage for dynamic pricing', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic',
+          },
+          quantity: 1,
+        },
+      ];
+      const result = getSubscriptionCreateSetup(items as any, 'usd', 0, 0, 5);
+      // Base: 1000, With 5% slippage: 1000 * 1.05 = 1050
+      expect(result.amount.setup).toBe('1050');
+    });
+
+    it('should apply custom 10% slippage for dynamic pricing', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic',
+          },
+          quantity: 1,
+        },
+      ];
+      const result = getSubscriptionCreateSetup(items as any, 'usd', 0, 0, 10);
+      // Base: 1000, With 10% slippage: 1000 * 1.10 = 1100
+      expect(result.amount.setup).toBe('1100');
+    });
+
+    it('should apply zero slippage when slippagePercent is 0', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic',
+          },
+          quantity: 1,
+        },
+      ];
+      const result = getSubscriptionCreateSetup(items as any, 'usd', 0, 0, 0);
+      // Base: 1000, With 0% slippage: 1000 * 1.00 = 1000
+      expect(result.amount.setup).toBe('1000');
+    });
+
+    it('should fallback to 0.5% slippage when slippagePercent is negative', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic',
+          },
+          quantity: 1,
+        },
+      ];
+      const result = getSubscriptionCreateSetup(items as any, 'usd', 0, 0, -1);
+      // Fallback to 0.5%: 1000 * 1.005 = 1005
+      expect(result.amount.setup).toBe('1005');
+    });
+
+    it('should fallback to 0.5% slippage when slippagePercent is NaN', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic',
+          },
+          quantity: 1,
+        },
+      ];
+      const result = getSubscriptionCreateSetup(items as any, 'usd', 0, 0, NaN);
+      // Fallback to 0.5%: 1000 * 1.005 = 1005
+      expect(result.amount.setup).toBe('1005');
+    });
+
+    it('should handle fractional slippage percentages (1.25%)', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic',
+          },
+          quantity: 1,
+        },
+      ];
+      const result = getSubscriptionCreateSetup(items as any, 'usd', 0, 0, 1.25);
+      // Base: 1000, With 1.25% slippage: multiplier = Math.round(1000 + 12.5) = 1013
+      // 1000 * 1013 / 1000 = 1013
+      expect(result.amount.setup).toBe('1013');
+    });
+
+    it('should NOT apply custom slippage for static pricing', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'fixed',
+          },
+          quantity: 1,
+        },
+      ];
+      const result = getSubscriptionCreateSetup(items as any, 'usd', 0, 0, 10);
+      // Static pricing: No slippage applied regardless of parameter
+      expect(result.amount.setup).toBe('1000');
+    });
+
+    // Tests for SlippageOptions object with minAcceptableRate
+    it('should accept SlippageOptions object with percent', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic',
+          },
+          quantity: 1,
+        },
+      ];
+      const result = getSubscriptionCreateSetup(items as any, 'usd', 0, 0, { percent: 5 });
+      // Base: 1000, With 5% slippage: 1000 * 1.05 = 1050
+      expect(result.amount.setup).toBe('1050');
+    });
+
+    it('should calculate authorization using minAcceptableRate when provided', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic',
+            base_amount: '100', // $100 USD
+          },
+          quantity: 1,
+        },
+      ];
+      // min_acceptable_rate = 0.5 means 1 token = $0.5 USD
+      // For $100 USD, we need: 100 / 0.5 = 200 tokens
+      const result = getSubscriptionCreateSetup(items as any, 'usd', 0, 0, {
+        percent: 5, // Should be ignored when minAcceptableRate is provided
+        minAcceptableRate: '0.5',
+        currencyDecimal: 0, // Simplified for testing
+      });
+      expect(result.amount.setup).toBe('200');
+    });
+
+    it('should use ceiling division for minAcceptableRate calculation', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic',
+            base_amount: '100', // $100 USD
+          },
+          quantity: 1,
+        },
+      ];
+      // min_acceptable_rate = 0.3 means 1 token = $0.3 USD
+      // For $100 USD, we need: ceil(100 / 0.3) = ceil(333.33) = 334 tokens
+      const result = getSubscriptionCreateSetup(items as any, 'usd', 0, 0, {
+        minAcceptableRate: '0.3',
+        currencyDecimal: 0,
+      });
+      expect(result.amount.setup).toBe('334');
+    });
+
+    it('should handle multiple dynamic pricing items with minAcceptableRate', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '500' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic',
+            base_amount: '50', // $50 USD
+          },
+          quantity: 2, // Total: $100 USD
+        },
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '250' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic',
+            base_amount: '25', // $25 USD
+          },
+          quantity: 2, // Total: $50 USD
+        },
+      ];
+      // Total base_amount: $100 + $50 = $150 USD
+      // min_acceptable_rate = 0.5 means 1 token = $0.5 USD
+      // For $150 USD, we need: 150 / 0.5 = 300 tokens
+      const result = getSubscriptionCreateSetup(items as any, 'usd', 0, 0, {
+        minAcceptableRate: '0.5',
+        currencyDecimal: 0,
+      });
+      expect(result.amount.setup).toBe('300');
+    });
+
+    it('should fallback to percent when minAcceptableRate is missing', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic',
+            base_amount: '100',
+          },
+          quantity: 1,
+        },
+      ];
+      const result = getSubscriptionCreateSetup(items as any, 'usd', 0, 0, {
+        percent: 10,
+        // minAcceptableRate is undefined
+        currencyDecimal: 0,
+      });
+      // Fallback to percent: 1000 * 1.10 = 1100
+      expect(result.amount.setup).toBe('1100');
+    });
+
+    it('should fallback to percent when currencyDecimal is missing', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic',
+            base_amount: '100',
+          },
+          quantity: 1,
+        },
+      ];
+      const result = getSubscriptionCreateSetup(items as any, 'usd', 0, 0, {
+        percent: 5,
+        minAcceptableRate: '0.5',
+        // currencyDecimal is undefined
+      });
+      // Fallback to percent: 1000 * 1.05 = 1050
+      expect(result.amount.setup).toBe('1050');
+    });
+
+    it('should fallback to percent when minAcceptableRate is zero', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic',
+            base_amount: '100',
+          },
+          quantity: 1,
+        },
+      ];
+      const result = getSubscriptionCreateSetup(items as any, 'usd', 0, 0, {
+        percent: 5,
+        minAcceptableRate: '0',
+        currencyDecimal: 0,
+      });
+      // Fallback to percent: 1000 * 1.05 = 1050
+      expect(result.amount.setup).toBe('1050');
+    });
+
+    it('should fallback to default 0.5% when SlippageOptions is empty object', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic',
+          },
+          quantity: 1,
+        },
+      ];
+      const result = getSubscriptionCreateSetup(items as any, 'usd', 0, 0, {});
+      // Fallback to default 0.5%: 1000 * 1.005 = 1005
+      expect(result.amount.setup).toBe('1005');
+    });
+
+    it('should handle minAcceptableRate with higher precision currencyDecimal', () => {
+      const items = [
+        {
+          price: {
+            type: 'recurring',
+            currency_options: [{ currency_id: 'eth', unit_amount: '100000000000000000' }], // 0.1 ETH in wei
+            recurring: { interval: 'month', interval_count: '1', usage_type: 'licensed' },
+            pricing_type: 'dynamic',
+            base_amount: '100', // $100 USD
+          },
+          quantity: 1,
+        },
+      ];
+      // min_acceptable_rate = 1000 means 1 token (wei) = $1000 USD
+      // But we have 18 decimals, so 1 ETH = $1000 * 10^18 / 10^18 = $1000
+      // For $100 USD with currencyDecimal=18:
+      // authorization = ceil(100 * 10^8 * 10^18 / (1000 * 10^8))
+      // = ceil(10^28 / 10^11) = ceil(10^17) = 100000000000000000 (0.1 ETH)
+      const result = getSubscriptionCreateSetup(items as any, 'eth', 0, 0, {
+        minAcceptableRate: '1000',
+        currencyDecimal: 18,
+      });
+      expect(result.amount.setup).toBe('100000000000000000');
+    });
+  });
 });
 
 describe('getCheckoutSessionSubscriptionIds', () => {