diff --git a/.changeset/fix-billing-typedoc-pages.md b/.changeset/fix-billing-typedoc-pages.md new file mode 100644 index 00000000000..4076e734edc --- /dev/null +++ b/.changeset/fix-billing-typedoc-pages.md @@ -0,0 +1,5 @@ +--- +'@clerk/shared': patch +--- + +Fix the Billing checkout Typedoc links. diff --git a/.typedoc/custom-plugin.mjs b/.typedoc/custom-plugin.mjs index bd7570adda0..6b0b71db41f 100644 --- a/.typedoc/custom-plugin.mjs +++ b/.typedoc/custom-plugin.mjs @@ -21,6 +21,7 @@ const FILES_WITHOUT_HEADINGS = [ 'organization-membership-public-user-data.mdx', 'checkout-signal-value.mdx', 'checkout-flow-resource.mdx', + 'update-checkout-params.mdx', 'use-checkout-options.mdx', 'use-payment-element-return.mdx', 'use-payment-methods-return.mdx', @@ -108,19 +109,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 +140,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 033ed8c65ef..332f8f01a37 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; durationInCycles?: number | null; } @@ -1060,20 +1130,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; } @@ -1232,6 +1348,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. @@ -1302,16 +1421,20 @@ export type CreateCheckoutParams = WithOptionalOrgType<{ * * @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 type UpdateCheckoutParams = WithOptionalOrgType<{ +export type UpdateCheckoutParams = { /** * The unique identifier for the checkout session. */ id: string; + /** + * The Organization ID to perform the request on. + */ + orgId?: string; /** * The promo code to apply. Use an empty string to remove the applied promo code. */ promoCode: string; -}>; +}; /** * The `confirm()` method accepts the following parameters. **Only one of `paymentMethodId`, `paymentToken`, or `useTestCard` should be provided.** @@ -1392,7 +1515,7 @@ export interface BillingCheckoutResource extends ClerkResource { */ totals: BillingTotals; /** - * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](#confirm) + * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](/docs/reference/types/billing-checkout-resource#confirm) */ confirm: (params: ConfirmCheckoutParams) => Promise; /** @@ -1542,12 +1665,12 @@ export interface CheckoutFlowFinalizeParams { */ interface CheckoutFlowMethods { /** - * Updates the current checkout. Use an empty promo code to remove the applied promo code. + * Updates the current checkout. Use an empty promo code to remove the applied promo code. [Learn more.](/docs/reference/types/billing-checkout-resource#update) */ update: (params: Pick) => Promise<{ error: ClerkError | null }>; /** - * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](#confirm) + * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](/docs/reference/types/billing-checkout-resource#confirm) */ confirm: (params: ConfirmCheckoutParams) => Promise<{ error: ClerkError | null }>; diff --git a/packages/shared/src/types/protectConfig.ts b/packages/shared/src/types/protectConfig.ts index d1fdb5e8714..8ea7fdf30a6 100644 --- a/packages/shared/src/types/protectConfig.ts +++ b/packages/shared/src/types/protectConfig.ts @@ -71,6 +71,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; @@ -85,5 +87,7 @@ export type ProtectAssertionResolver = () => string | undefined | Promise