diff --git a/.changeset/fix-billing-typedoc-pages.md b/.changeset/fix-billing-typedoc-pages.md new file mode 100644 index 00000000000..a845151cc84 --- /dev/null +++ b/.changeset/fix-billing-typedoc-pages.md @@ -0,0 +1,2 @@ +--- +--- diff --git a/.typedoc/custom-plugin.mjs b/.typedoc/custom-plugin.mjs index bd7570adda0..a947b3f4bc8 100644 --- a/.typedoc/custom-plugin.mjs +++ b/.typedoc/custom-plugin.mjs @@ -108,19 +108,30 @@ const LINK_REPLACEMENTS = [ ['invitation', '/docs/reference/backend/types/backend-invitation'], ['verify-token-options', '#verify-token-options'], ['localization-resource', '/docs/guides/customizing-clerk/localization'], - ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#parameters'], + ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#confirm-parameters'], + ['update-checkout-params', '/docs/reference/types/billing-checkout-resource#update-parameters'], + ['billing-applied-discount', '/docs/reference/types/billing-applied-discount'], + ['billing-credits', '/docs/reference/types/billing-credits'], + ['billing-discount-redemption', '/docs/reference/types/billing-discount-redemption'], + ['billing-discounts', '/docs/reference/types/billing-discounts'], + ['billing-payment-totals', '/docs/reference/types/billing-payment-totals'], ['billing-payment-method-resource', '/docs/reference/types/billing-payment-method-resource'], + ['billing-payer-credit', '/docs/reference/types/billing-payer-credit'], ['billing-payer-resource', '/docs/reference/types/billing-payer-resource'], + ['billing-period-totals', '/docs/reference/types/billing-period-totals'], ['billing-plan-price', '/docs/reference/types/billing-plan-price'], ['billing-plan-resource', '/docs/reference/types/billing-plan-resource'], ['billing-plan-unit-price', '/docs/reference/types/billing-plan-unit-price'], ['billing-plan-unit-price-tier', '/docs/reference/types/billing-plan-unit-price-tier'], + ['billing-proration-discount', '/docs/reference/types/billing-proration-discount'], + ['billing-proration-credit-detail', '/docs/reference/types/billing-proration-credit-detail'], ['billing-checkout-totals', '/docs/reference/types/billing-checkout-totals'], ['billing-checkout-resource', '/docs/reference/types/billing-checkout-resource'], ['billing-money-amount', '/docs/reference/types/billing-money-amount'], ['billing-per-unit-total', '/docs/reference/types/billing-per-unit-total'], ['billing-per-unit-total-tier', '/docs/reference/types/billing-per-unit-total-tier'], ['billing-subscription-item-resource', '/docs/reference/types/billing-subscription-item-resource'], + ['billing-subscription-item-next-payment', '/docs/reference/types/billing-subscription-item-next-payment'], ['billing-subscription-item-seats', '/docs/reference/types/billing-subscription-item-seats'], ['billing-subscription-item-status', '/docs/reference/backend/types/billing-subscription-item-status'], ['feature-resource', '/docs/reference/types/feature-resource'], @@ -128,6 +139,7 @@ const LINK_REPLACEMENTS = [ ['billing-statement-resource', '/docs/reference/types/billing-statement-resource'], ['billing-totals', '/docs/reference/types/billing-totals'], ['billing-subscription-resource', '/docs/reference/types/billing-subscription-resource'], + ['billing-subscription-next-payment', '/docs/reference/types/billing-subscription-next-payment'], ['clerk-api-response-error', '/docs/reference/types/clerk-api-response-error'], ['clerk-api-error', '/docs/reference/types/clerk-api-error'], ['billing-statement-totals', '/docs/reference/types/billing-statement-totals'], diff --git a/packages/shared/src/types/billing.ts b/packages/shared/src/types/billing.ts index 5d90e45d24b..bcf7951d9ed 100644 --- a/packages/shared/src/types/billing.ts +++ b/packages/shared/src/types/billing.ts @@ -852,6 +852,9 @@ export interface BillingSubscriptionItemResource extends ClerkResource { */ amount: BillingMoneyAmount; }; + /** + * The credits applied to this subscription item. + */ credits?: BillingCredits; /** * The active discount applied to this subscription item. @@ -994,21 +997,63 @@ export interface BillingMoneyAmount { currencySymbol: string; } +/** + * Contains details about a proration credit, including the remaining portion of the billing cycle. + * + * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. + */ export interface BillingProrationCreditDetail { + /** + * The monetary value of the proration credit. + */ amount: BillingMoneyAmount; + /** + * The number of days remaining in the current billing cycle. + */ cycleDaysRemaining: number; + /** + * The total number of days in the billing cycle. + */ cycleDaysTotal: number; + /** + * The percentage of the billing cycle that remains. + */ cycleRemainingPercent: number; } +/** + * Contains details about the payer's available credit and the amount applied to the transaction. + * + * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. + */ export interface BillingPayerCredit { + /** + * The payer's credit balance remaining after the transaction. + */ remainingBalance: BillingMoneyAmount; + /** + * The amount of payer credit applied to the transaction. + */ appliedAmount: BillingMoneyAmount; } +/** + * The `BillingCredits` type represents the credits applied to a checkout or payment. + * + * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. + */ export interface BillingCredits { + /** + * The credit for the unused portion of the current billing cycle. `null` when no proration credit applies. + */ proration: BillingProrationCreditDetail | null; + /** + * The payer credit applied to the transaction. `null` when no payer credit applies. + */ payer: BillingPayerCredit | null; + /** + * The total monetary value of all credits applied to the transaction. + */ total: BillingMoneyAmount; } @@ -1043,13 +1088,38 @@ export interface BillingProrationDiscount { * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. */ export interface BillingAppliedDiscount { + /** + * The monetary value of the discount applied to the transaction. + */ amount: BillingMoneyAmount; + /** + * The unique identifier of the discount. + */ discountId: string; + /** + * The display name of the discount. + */ name: string; + /** + * Whether the discount subtracts a percentage or a fixed amount. + */ effect: 'percentage' | 'fixed_amount'; + /** + * The percentage deducted when `effect` is `'percentage'`. + */ percentOff?: number; + /** + * The monetary value deducted when `effect` is `'fixed_amount'`. + */ amountOff?: BillingMoneyAmount; + /** + * The promotion code used to apply the discount. + */ promoCode?: string; + /** + * The number of billing cycles for which the discount remains active. `null` means the discount does not expire + * after a fixed number of cycles. + */ cyclesRemaining: number | null; } @@ -1059,20 +1129,66 @@ export interface BillingAppliedDiscount { * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. */ export interface BillingDiscountRedemption { + /** + * The unique identifier of the discount redemption. + */ id: string; + /** + * The unique identifier of the subscription item receiving the discount. + */ subscriptionItemId: string; + /** + * The unique identifier of the redeemed discount. + */ discountId: string; + /** + * The display name of the discount. + */ name: string; + /** + * How the discount was applied to the subscription item. + */ source: 'promotion' | 'manual' | 'promo_code'; + /** + * The promotion code used to redeem the discount. + */ promoCode?: string; + /** + * Whether the discount subtracts a percentage or a fixed amount. + */ effect?: 'percentage' | 'fixed_amount'; + /** + * The percentage deducted when `effect` is `'percentage'`. + */ percentOff?: number; + /** + * The monetary value deducted when `effect` is `'fixed_amount'`. + */ amountOff?: BillingMoneyAmount; + /** + * The monetary value of the discount applied to the subscription item. + */ amount?: BillingMoneyAmount; + /** + * The number of billing cycles for which the discount remains active. `null` means the discount does not expire + * after a fixed number of cycles. + */ cyclesRemaining: number | null; + /** + * The number of billing cycles to which the discount has already been applied. + */ cyclesApplied: number; + /** + * The current status of the discount redemption. + */ status?: 'active' | 'exhausted' | 'removed'; + /** + * The date and time when the discount was redeemed. + */ redeemedAt: Date; + /** + * The identifier of the user who redeemed the discount. `null` if no user was recorded. + */ redeemedBy: string | null; } @@ -1231,6 +1347,9 @@ export interface BillingCheckoutTotals { * Any credits (like account balance or promo credits) that are being applied to the checkout. */ credit: BillingMoneyAmount | null; + /** + * The credits applied to the checkout. `null` when no credits apply. + */ credits: BillingCredits | null; /** * Any outstanding amount from previous unpaid invoices that is being collected as part of the checkout. diff --git a/packages/shared/src/types/protectConfig.ts b/packages/shared/src/types/protectConfig.ts index 7f469757a41..15949d26eff 100644 --- a/packages/shared/src/types/protectConfig.ts +++ b/packages/shared/src/types/protectConfig.ts @@ -28,6 +28,8 @@ export interface ProtectConfigResource extends ClerkResource { * Called per request, so a token refreshed in the background is picked up without * re-configuring Clerk. It must not throw, and a rejected promise is treated the same as * `undefined`: an assertion may influence a sign-in, but never prevent one. + * + * @inline */ export type ProtectAssertionResolver = () => string | undefined | Promise; @@ -42,5 +44,7 @@ export type ProtectAssertionResolver = () => string | undefined | Promise