From d629933662b5536bebc77f1fd5592748bcfa0f4f Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Tue, 11 Aug 2026 11:54:27 +0100 Subject: [PATCH 1/9] Fixing initial broken links --- .typedoc/custom-plugin.mjs | 1 + packages/shared/src/types/billing.ts | 71 ++++++++++++++++++++++ packages/shared/src/types/protectConfig.ts | 4 ++ 3 files changed, 76 insertions(+) diff --git a/.typedoc/custom-plugin.mjs b/.typedoc/custom-plugin.mjs index bd7570adda0..2328e6c85e9 100644 --- a/.typedoc/custom-plugin.mjs +++ b/.typedoc/custom-plugin.mjs @@ -121,6 +121,7 @@ const LINK_REPLACEMENTS = [ ['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-resource-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'], diff --git a/packages/shared/src/types/billing.ts b/packages/shared/src/types/billing.ts index 5d90e45d24b..5b703628ae1 100644 --- a/packages/shared/src/types/billing.ts +++ b/packages/shared/src/types/billing.ts @@ -1043,13 +1043,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 +1084,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; } 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 Date: Tue, 11 Aug 2026 12:54:23 +0100 Subject: [PATCH 2/9] Add more fixes --- .typedoc/custom-plugin.mjs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.typedoc/custom-plugin.mjs b/.typedoc/custom-plugin.mjs index 2328e6c85e9..0d967f93b5e 100644 --- a/.typedoc/custom-plugin.mjs +++ b/.typedoc/custom-plugin.mjs @@ -109,8 +109,10 @@ const LINK_REPLACEMENTS = [ ['verify-token-options', '#verify-token-options'], ['localization-resource', '/docs/guides/customizing-clerk/localization'], ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#parameters'], + ['billing-discounts', '/docs/reference/types/billing-discounts'], ['billing-payment-method-resource', '/docs/reference/types/billing-payment-method-resource'], ['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'], From 3a794436fdb716f7a4298a6bf7ec686e442a5b8b Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Tue, 11 Aug 2026 13:10:48 +0100 Subject: [PATCH 3/9] More fixes --- .typedoc/custom-plugin.mjs | 3 ++ packages/shared/src/types/billing.ts | 42 ++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+) diff --git a/.typedoc/custom-plugin.mjs b/.typedoc/custom-plugin.mjs index 0d967f93b5e..b0ffa8d84ad 100644 --- a/.typedoc/custom-plugin.mjs +++ b/.typedoc/custom-plugin.mjs @@ -109,14 +109,17 @@ const LINK_REPLACEMENTS = [ ['verify-token-options', '#verify-token-options'], ['localization-resource', '/docs/guides/customizing-clerk/localization'], ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#parameters'], + ['billing-credits', '/docs/reference/types/billing-credits'], ['billing-discounts', '/docs/reference/types/billing-discounts'], ['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-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'], diff --git a/packages/shared/src/types/billing.ts b/packages/shared/src/types/billing.ts index 5b703628ae1..a6acffe606b 100644 --- a/packages/shared/src/types/billing.ts +++ b/packages/shared/src/types/billing.ts @@ -994,21 +994,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; } From b0bb61cbe6b6552c896a00e2a6568890c3d82213 Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Tue, 11 Aug 2026 13:16:43 +0100 Subject: [PATCH 4/9] Add more replacement links --- .typedoc/custom-plugin.mjs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.typedoc/custom-plugin.mjs b/.typedoc/custom-plugin.mjs index b0ffa8d84ad..0d06714674a 100644 --- a/.typedoc/custom-plugin.mjs +++ b/.typedoc/custom-plugin.mjs @@ -111,6 +111,7 @@ const LINK_REPLACEMENTS = [ ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#parameters'], ['billing-credits', '/docs/reference/types/billing-credits'], ['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'], @@ -119,6 +120,7 @@ const LINK_REPLACEMENTS = [ ['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'], @@ -126,7 +128,7 @@ const LINK_REPLACEMENTS = [ ['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-resource-next-payment'], + ['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'], @@ -134,6 +136,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'], From 49c96a9740235c95c88256b64c87b191c3324dd8 Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Tue, 11 Aug 2026 13:51:05 +0100 Subject: [PATCH 5/9] Add changeset and remaining fixes --- .changeset/fix-billing-typedoc-pages.md | 2 ++ .typedoc/custom-plugin.mjs | 2 ++ packages/shared/src/types/billing.ts | 6 ++++++ 3 files changed, 10 insertions(+) create mode 100644 .changeset/fix-billing-typedoc-pages.md 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 0d06714674a..06eb4ad9678 100644 --- a/.typedoc/custom-plugin.mjs +++ b/.typedoc/custom-plugin.mjs @@ -109,7 +109,9 @@ const LINK_REPLACEMENTS = [ ['verify-token-options', '#verify-token-options'], ['localization-resource', '/docs/guides/customizing-clerk/localization'], ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#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'], diff --git a/packages/shared/src/types/billing.ts b/packages/shared/src/types/billing.ts index a6acffe606b..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. @@ -1344,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. From fbcf77cd51cd32e14ac88be7fd4b0bcdd958c9b0 Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Tue, 11 Aug 2026 17:03:04 +0100 Subject: [PATCH 6/9] Fix UpdateCheckoutParams --- packages/shared/src/types/billing.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/shared/src/types/billing.ts b/packages/shared/src/types/billing.ts index bcf7951d9ed..c09e09297a4 100644 --- a/packages/shared/src/types/billing.ts +++ b/packages/shared/src/types/billing.ts @@ -1418,6 +1418,8 @@ export type CreateCheckoutParams = WithOptionalOrgType<{ /** * The `updateCheckout()` method accepts the following parameters. * + * @inline + * * @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<{ From 8427edae3b134a9cce5328052aa60f3bb7a49e61 Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Tue, 11 Aug 2026 17:17:41 +0100 Subject: [PATCH 7/9] Fix updateCheckoutParams --- .typedoc/custom-plugin.mjs | 3 ++- packages/shared/src/types/billing.ts | 2 -- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/.typedoc/custom-plugin.mjs b/.typedoc/custom-plugin.mjs index 06eb4ad9678..a947b3f4bc8 100644 --- a/.typedoc/custom-plugin.mjs +++ b/.typedoc/custom-plugin.mjs @@ -108,7 +108,8 @@ 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'], diff --git a/packages/shared/src/types/billing.ts b/packages/shared/src/types/billing.ts index c09e09297a4..bcf7951d9ed 100644 --- a/packages/shared/src/types/billing.ts +++ b/packages/shared/src/types/billing.ts @@ -1418,8 +1418,6 @@ export type CreateCheckoutParams = WithOptionalOrgType<{ /** * The `updateCheckout()` method accepts the following parameters. * - * @inline - * * @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<{ From d858aab0e27515d3dfa4e9f452a117eb4d0d5b90 Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Thu, 13 Aug 2026 16:22:51 +0100 Subject: [PATCH 8/9] Add remaining fixes --- .changeset/fix-billing-typedoc-pages.md | 3 +++ .typedoc/custom-plugin.mjs | 1 + packages/shared/src/types/billing.ts | 14 +++++++++----- 3 files changed, 13 insertions(+), 5 deletions(-) diff --git a/.changeset/fix-billing-typedoc-pages.md b/.changeset/fix-billing-typedoc-pages.md index a845151cc84..4076e734edc 100644 --- a/.changeset/fix-billing-typedoc-pages.md +++ b/.changeset/fix-billing-typedoc-pages.md @@ -1,2 +1,5 @@ --- +'@clerk/shared': patch --- + +Fix the Billing checkout Typedoc links. diff --git a/.typedoc/custom-plugin.mjs b/.typedoc/custom-plugin.mjs index a947b3f4bc8..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', diff --git a/packages/shared/src/types/billing.ts b/packages/shared/src/types/billing.ts index bcf7951d9ed..8033ca80d75 100644 --- a/packages/shared/src/types/billing.ts +++ b/packages/shared/src/types/billing.ts @@ -1420,16 +1420,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.** @@ -1510,7 +1514,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; /** @@ -1660,12 +1664,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 }>; From 763376ed45d488a3023f416c0b9d647b72907f74 Mon Sep 17 00:00:00 2001 From: Michael Novotny Date: Fri, 14 Aug 2026 13:43:23 -0500 Subject: [PATCH 9/9] Document remaining billing fields and cover link replacements - Add JSDoc for BillingAppliedDiscount.durationInCycles so excludeNotDocumented no longer drops it from the generated page - Clarify amountOff as the configured fixed amount vs the applied amount - Use absolute clerk.com doc URLs so the links resolve in IntelliSense - Add unit tests for the relative link replacements Co-Authored-By: Claude Opus 4.8 --- .changeset/fix-billing-typedoc-pages.md | 2 +- .../relative-link-replacements.test.ts | 90 +++++++++++++++++++ packages/shared/src/types/billing.ts | 16 ++-- 3 files changed, 102 insertions(+), 6 deletions(-) create mode 100644 .typedoc/__tests__/relative-link-replacements.test.ts diff --git a/.changeset/fix-billing-typedoc-pages.md b/.changeset/fix-billing-typedoc-pages.md index 4076e734edc..4a1c4271939 100644 --- a/.changeset/fix-billing-typedoc-pages.md +++ b/.changeset/fix-billing-typedoc-pages.md @@ -2,4 +2,4 @@ '@clerk/shared': patch --- -Fix the Billing checkout Typedoc links. +Fix broken Billing TypeDoc links and add missing JSDoc descriptions for the credit and discount types. diff --git a/.typedoc/__tests__/relative-link-replacements.test.ts b/.typedoc/__tests__/relative-link-replacements.test.ts new file mode 100644 index 00000000000..cf98e65efb9 --- /dev/null +++ b/.typedoc/__tests__/relative-link-replacements.test.ts @@ -0,0 +1,90 @@ +import { describe, expect, it } from 'vitest'; + +// @ts-expect-error — .mjs plugin has no type declarations +import { applyRelativeLinkReplacements } from '../custom-plugin.mjs'; + +/** + * Unit coverage for the `LINK_REPLACEMENTS` rules exercised through the exported + * `applyRelativeLinkReplacements()` entry point. These guard the Billing checkout + * links so an incorrect route or anchor cannot silently pass CI. + */ +describe('applyRelativeLinkReplacements', () => { + const cases: Array<[label: string, input: string, expected: string]> = [ + [ + 'confirm-checkout-params routes to the #confirm-parameters section', + '[x](confirm-checkout-params.mdx)', + '[x](/docs/reference/types/billing-checkout-resource#confirm-parameters)', + ], + [ + 'update-checkout-params routes to the #update-parameters section', + '[x](update-checkout-params.mdx)', + '[x](/docs/reference/types/billing-checkout-resource#update-parameters)', + ], + [ + 'preserves an anchor from the source link', + '[x](billing-credits.mdx#total)', + '[x](/docs/reference/types/billing-credits#total)', + ], + [ + 'billing-credits routes to its standalone page', + '[x](billing-credits.mdx)', + '[x](/docs/reference/types/billing-credits)', + ], + [ + 'billing-applied-discount routes to its standalone page', + '[x](billing-applied-discount.mdx)', + '[x](/docs/reference/types/billing-applied-discount)', + ], + [ + 'billing-discount-redemption routes to its standalone page', + '[x](billing-discount-redemption.mdx)', + '[x](/docs/reference/types/billing-discount-redemption)', + ], + [ + 'billing-payer-credit routes to its standalone page', + '[x](billing-payer-credit.mdx)', + '[x](/docs/reference/types/billing-payer-credit)', + ], + [ + 'billing-proration-credit-detail routes to its standalone page', + '[x](billing-proration-credit-detail.mdx)', + '[x](/docs/reference/types/billing-proration-credit-detail)', + ], + [ + 'resolves relative path prefixes', + '[x](../../types/billing-credits.mdx)', + '[x](/docs/reference/types/billing-credits)', + ], + [ + 'resolves nested object-doc links', + '[x](billing-credits/billing-credits.mdx)', + '[x](/docs/reference/types/billing-credits)', + ], + ]; + + it.each(cases)('%s', (_label, input, expected) => { + expect(applyRelativeLinkReplacements(input)).toBe(expected); + }); + + it('routes the two sibling next-payment pages independently', () => { + expect(applyRelativeLinkReplacements('[x](billing-subscription-item-next-payment.mdx)')).toBe( + '[x](/docs/reference/types/billing-subscription-item-next-payment)', + ); + expect(applyRelativeLinkReplacements('[x](billing-subscription-next-payment.mdx)')).toBe( + '[x](/docs/reference/types/billing-subscription-next-payment)', + ); + }); + + it('does not rewrite a page whose name is a prefix of a replacement key', () => { + // `billing-payer` is a prefix of `billing-payer-credit`, but the `.mdx` boundary + // must keep an unrelated `billing-payer-resource.mdx` link from being mis-routed. + expect(applyRelativeLinkReplacements('[x](billing-payer-resource.mdx)')).toBe( + '[x](/docs/reference/types/billing-payer-resource)', + ); + }); + + it('leaves content without matching links untouched', () => { + expect(applyRelativeLinkReplacements('no links here')).toBe('no links here'); + expect(applyRelativeLinkReplacements('')).toBe(''); + }); +}); diff --git a/packages/shared/src/types/billing.ts b/packages/shared/src/types/billing.ts index 332f8f01a37..7cbc0a577fd 100644 --- a/packages/shared/src/types/billing.ts +++ b/packages/shared/src/types/billing.ts @@ -1109,7 +1109,8 @@ export interface BillingAppliedDiscount { */ percentOff?: number; /** - * The monetary value deducted when `effect` is `'fixed_amount'`. + * The configured fixed amount off when `effect` is `'fixed_amount'`. This is the discount's configured value, which + * can differ from the `amount` actually applied to the transaction. */ amountOff?: BillingMoneyAmount; /** @@ -1121,6 +1122,10 @@ export interface BillingAppliedDiscount { * after a fixed number of cycles. */ cyclesRemaining: number | null; + /** + * The originally configured duration in billing cycles. `null` means the discount does not expire after a fixed + * number of cycles. + */ durationInCycles?: number | null; } @@ -1163,7 +1168,8 @@ export interface BillingDiscountRedemption { */ percentOff?: number; /** - * The monetary value deducted when `effect` is `'fixed_amount'`. + * The configured fixed amount off when `effect` is `'fixed_amount'`. This is the discount's configured value, which + * can differ from the `amount` actually applied to the transaction. */ amountOff?: BillingMoneyAmount; /** @@ -1515,7 +1521,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.](/docs/reference/types/billing-checkout-resource#confirm) + * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#confirm) */ confirm: (params: ConfirmCheckoutParams) => Promise; /** @@ -1665,12 +1671,12 @@ export interface CheckoutFlowFinalizeParams { */ interface CheckoutFlowMethods { /** - * Updates the current checkout. Use an empty promo code to remove the applied promo code. [Learn more.](/docs/reference/types/billing-checkout-resource#update) + * Updates the current checkout. Use an empty promo code to remove the applied promo code. [Learn more.](https://clerk.com/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.](/docs/reference/types/billing-checkout-resource#confirm) + * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#confirm) */ confirm: (params: ConfirmCheckoutParams) => Promise<{ error: ClerkError | null }>;