fix(clerk-js,shared): Update type for next_payment

packages/clerk-js/src/core/resources/BillingCheckout.ts

@@ -4,7 +4,7 @@ import { retry } from '@clerk/shared/retry';
 import type {
   BillingCheckoutJSON,
   BillingCheckoutResource,
-  BillingCheckoutTotals,
+  BillingTotals,
   BillingPayerResource,
   BillingPaymentMethodResource,
   BillingSubscriptionPlanPeriod,
@@ -34,7 +34,7 @@ export class BillingCheckout extends BaseResource implements BillingCheckoutReso
   planPeriod!: BillingSubscriptionPlanPeriod;
   planPeriodStart!: number | undefined;
   status!: 'needs_confirmation' | 'completed';
-  totals!: BillingCheckoutTotals;
+  totals!: BillingTotals;
   isImmediatePlanChange!: boolean;
   freeTrialEndsAt?: Date;
   payer!: BillingPayerResource;

packages/clerk-js/src/core/resources/BillingStatement.ts

@@ -6,7 +6,7 @@ import type {
   BillingStatementTotals,
 } from '@clerk/shared/types';
 
-import { billingTotalsFromJSON } from '../../utils';
+import { billingStatementTotalsFromJSON } from '../../utils';
 import { unixEpochToDate } from '../../utils/date';
 import { BaseResource, BillingPayment } from './internal';
 
@@ -30,7 +30,7 @@ export class BillingStatement extends BaseResource implements BillingStatementRe
     this.id = data.id;
     this.status = data.status;
     this.timestamp = unixEpochToDate(data.timestamp);
-    this.totals = billingTotalsFromJSON(data.totals);
+    this.totals = billingStatementTotalsFromJSON(data.totals);
     this.groups = data.groups.map(group => new BillingStatementGroup(group));
     return this;
   }

packages/clerk-js/src/core/resources/BillingSubscription.ts

@@ -1,6 +1,8 @@
 import type {
   BillingCredits,
   BillingMoneyAmount,
+  BillingSubscriptionItemNextPayment,
+  BillingSubscriptionNextPayment,
   BillingSubscriptionItemJSON,
   BillingSubscriptionItemResource,
   BillingSubscriptionItemSeats,
@@ -14,7 +16,12 @@ import type {
 
 import { unixEpochToDate } from '@/utils/date';
 
-import { billingCreditsFromJSON, billingMoneyAmountFromJSON } from '../../utils';
+import {
+  billingCreditsFromJSON,
+  billingMoneyAmountFromJSON,
+  billingSubscriptionItemNextPaymentFromJSON,
+  billingSubscriptionNextPaymentFromJSON,
+} from '../../utils';
 import { Billing } from '../modules/billing/namespace';
 import { BaseResource, BillingPlan, DeletedObject } from './internal';
 
@@ -25,10 +32,7 @@ export class BillingSubscription extends BaseResource implements BillingSubscrip
   createdAt!: Date;
   pastDueAt!: Date | null;
   updatedAt!: Date | null;
-  nextPayment?: {
-    amount: BillingMoneyAmount;
-    date: Date;
-  };
+  nextPayment?: BillingSubscriptionNextPayment | null;
   subscriptionItems!: BillingSubscriptionItemResource[];
   eligibleForFreeTrial!: boolean;
 
@@ -49,12 +53,12 @@ export class BillingSubscription extends BaseResource implements BillingSubscrip
     this.activeAt = unixEpochToDate(data.active_at);
     this.pastDueAt = data.past_due_at ? unixEpochToDate(data.past_due_at) : null;
 
-    if (data.next_payment) {
-      this.nextPayment = {
-        amount: billingMoneyAmountFromJSON(data.next_payment.amount),
-        date: unixEpochToDate(data.next_payment.date),
-      };
-    }
+    this.nextPayment =
+      data.next_payment === undefined
+        ? undefined
+        : data.next_payment === null
+          ? null
+          : billingSubscriptionNextPaymentFromJSON(data.next_payment);
 
     this.subscriptionItems = (data.subscription_items || []).map(item => new BillingSubscriptionItem(item));
     this.eligibleForFreeTrial = this.withDefault(data.eligible_for_free_trial, false);
@@ -80,6 +84,7 @@ export class BillingSubscriptionItem extends BaseResource implements BillingSubs
   };
   seats?: BillingSubscriptionItemSeats;
   credits?: BillingCredits;
+  nextPayment?: BillingSubscriptionItemNextPayment | null;
   isFreeTrial!: boolean;
 
   constructor(data: BillingSubscriptionItemJSON) {
@@ -111,6 +116,12 @@ export class BillingSubscriptionItem extends BaseResource implements BillingSubs
     this.seats = data.seats ? { quantity: data.seats.quantity } : undefined;
 
     this.credits = data.credits ? billingCreditsFromJSON(data.credits) : undefined;
+    this.nextPayment =
+      data.next_payment === undefined
+        ? undefined
+        : data.next_payment === null
+          ? null
+          : billingSubscriptionItemNextPaymentFromJSON(data.next_payment);
 
     this.isFreeTrial = this.withDefault(data.is_free_trial, false);
     return this;

packages/clerk-js/src/utils/__tests__/billing.test.ts

@@ -1,7 +1,17 @@
-import type { BillingMoneyAmountJSON, BillingPaymentTotalsJSON } from '@clerk/shared/types';
+import type {
+  BillingMoneyAmountJSON,
+  BillingPaymentTotalsJSON,
+  BillingSubscriptionItemNextPaymentJSON,
+  BillingSubscriptionNextPaymentJSON,
+  BillingTotalsJSON,
+} from '@clerk/shared/types';
 import { describe, expect, it } from 'vitest';
 
-import { billingPaymentTotalsFromJSON } from '../billing';
+import {
+  billingPaymentTotalsFromJSON,
+  billingSubscriptionItemNextPaymentFromJSON,
+  billingSubscriptionNextPaymentFromJSON,
+} from '../billing';
 
 const moneyJSON = (amount: number): BillingMoneyAmountJSON => ({
   amount,
@@ -10,6 +20,55 @@ const moneyJSON = (amount: number): BillingMoneyAmountJSON => ({
   currency_symbol: '$',
 });
 
+const nextPaymentTotalsJSON = (): BillingTotalsJSON => ({
+  subtotal: moneyJSON(5000),
+  base_fee: moneyJSON(1000),
+  tax_total: moneyJSON(500),
+  grand_total: moneyJSON(5500),
+  credits: {
+    proration: null,
+    payer: {
+      remaining_balance: moneyJSON(2000),
+      applied_amount: moneyJSON(1000),
+    },
+    total: moneyJSON(1000),
+  },
+  discounts: {
+    proration: {
+      amount: moneyJSON(500),
+      cycle_days_passed: 15,
+      cycle_days_total: 30,
+      cycle_passed_percent: 50,
+    },
+    total: moneyJSON(500),
+  },
+  total_due_after_free_trial: null,
+  credit: null,
+  past_due: null,
+  total_due_now: moneyJSON(4500),
+  per_unit_totals: [
+    {
+      name: 'seats',
+      block_size: 1,
+      tiers: [{ quantity: 5, fee_per_block: moneyJSON(1000), total: moneyJSON(5000) }],
+    },
+  ],
+  totals_due_per_period: {
+    subtotal: moneyJSON(10000),
+    base_fee: moneyJSON(1000),
+    tax_total: moneyJSON(1000),
+    grand_total: moneyJSON(11000),
+    per_unit_totals: [
+      {
+        name: 'seats',
+        block_size: 1,
+        tiers: [{ quantity: 10, fee_per_block: moneyJSON(1000), total: moneyJSON(10000) }],
+      },
+    ],
+  },
+  total_due_per_period: moneyJSON(11000),
+});
+
 describe('billingPaymentTotalsFromJSON', () => {
   it('maps subtotal, grand_total, and tax_total', () => {
     const data: BillingPaymentTotalsJSON = {
@@ -68,3 +127,100 @@ describe('billingPaymentTotalsFromJSON', () => {
     expect(totals.perUnitTotals?.[0].tiers[1].quantity).toBeNull();
   });
 });
+
+describe('billingSubscriptionNextPaymentFromJSON', () => {
+  it('maps amount, date, and per_unit_totals', () => {
+    const data: BillingSubscriptionNextPaymentJSON = {
+      amount: moneyJSON(5000),
+      date: 1_609_459_200_000,
+      per_unit_totals: [
+        {
+          name: 'seats',
+          block_size: 1,
+          tiers: [{ quantity: 5, fee_per_block: moneyJSON(1000), total: moneyJSON(5000) }],
+        },
+      ],
+      totals: nextPaymentTotalsJSON(),
+    };
+
+    const nextPayment = billingSubscriptionNextPaymentFromJSON(data);
+
+    expect(nextPayment.amount.amount).toBe(5000);
+    expect(nextPayment.date).toEqual(new Date('2021-01-01T00:00:00.000Z'));
+    expect(nextPayment.perUnitTotals?.[0]).toMatchObject({
+      name: 'seats',
+      blockSize: 1,
+      tiers: [{ quantity: 5, feePerBlock: { amount: 1000 }, total: { amount: 5000 } }],
+    });
+    expect(nextPayment.totals).toMatchObject({
+      subtotal: { amount: 5000 },
+      baseFee: { amount: 1000 },
+      taxTotal: { amount: 500 },
+      grandTotal: { amount: 5500 },
+      totalDueAfterFreeTrial: null,
+      credit: null,
+      pastDue: null,
+      totalDueNow: { amount: 4500 },
+      totalDuePerPeriod: { amount: 11000 },
+      credits: {
+        payer: {
+          remainingBalance: { amount: 2000 },
+          appliedAmount: { amount: 1000 },
+        },
+        total: { amount: 1000 },
+      },
+      discounts: {
+        proration: {
+          amount: { amount: 500 },
+          cycleDaysPassed: 15,
+          cycleDaysTotal: 30,
+          cyclePassedPercent: 50,
+        },
+        total: { amount: 500 },
+      },
+      perUnitTotals: [{ name: 'seats', blockSize: 1 }],
+      totalsDuePerPeriod: {
+        subtotal: { amount: 10000 },
+        baseFee: { amount: 1000 },
+        taxTotal: { amount: 1000 },
+        grandTotal: { amount: 11000 },
+        perUnitTotals: [{ name: 'seats', blockSize: 1 }],
+      },
+    });
+  });
+});
+
+describe('billingSubscriptionItemNextPaymentFromJSON', () => {
+  it('maps amount, date, and per_unit_totals', () => {
+    const data: BillingSubscriptionItemNextPaymentJSON = {
+      amount: moneyJSON(5000),
+      date: 1_609_459_200_000,
+      per_unit_totals: [
+        {
+          name: 'seats',
+          block_size: 1,
+          tiers: [{ quantity: 5, fee_per_block: moneyJSON(1000), total: moneyJSON(5000) }],
+        },
+      ],
+      totals: nextPaymentTotalsJSON(),
+    };
+
+    const nextPayment = billingSubscriptionItemNextPaymentFromJSON(data);
+
+    expect(nextPayment.amount.amount).toBe(5000);
+    expect(nextPayment.date).toEqual(new Date('2021-01-01T00:00:00.000Z'));
+    expect(nextPayment.perUnitTotals?.[0]).toMatchObject({
+      name: 'seats',
+      blockSize: 1,
+      tiers: [{ quantity: 5, feePerBlock: { amount: 1000 }, total: { amount: 5000 } }],
+    });
+    expect(nextPayment.totals).toMatchObject({
+      subtotal: { amount: 5000 },
+      baseFee: { amount: 1000 },
+      totalDueNow: { amount: 4500 },
+      credits: { total: { amount: 1000 } },
+      discounts: { total: { amount: 500 } },
+      perUnitTotals: [{ name: 'seats', blockSize: 1 }],
+    });
+  });
+});