diff --git a/.changeset/three-knives-play.md b/.changeset/three-knives-play.md new file mode 100644 index 00000000000..81553f188d8 --- /dev/null +++ b/.changeset/three-knives-play.md @@ -0,0 +1,7 @@ +--- +'@clerk/backend': patch +'@clerk/types': patch +--- + +- Export `Feature` type from backend resource. +- Re-export canonical `CommerceMoneyAmount` type from `@clerk/types`. diff --git a/.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap b/.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap index d91b3a1c8b0..5a938e52d48 100644 --- a/.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap +++ b/.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap @@ -232,6 +232,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = ` "backend/commerce-subscription.mdx", "backend/email-address.mdx", "backend/external-account.mdx", + "backend/feature.mdx", "backend/get-auth-fn.mdx", "backend/identification-link.mdx", "backend/infer-auth-object-from-token-array.mdx", diff --git a/.typedoc/custom-plugin.mjs b/.typedoc/custom-plugin.mjs index ee584a16964..904d1e4cf35 100644 --- a/.typedoc/custom-plugin.mjs +++ b/.typedoc/custom-plugin.mjs @@ -55,6 +55,7 @@ const LINK_REPLACEMENTS = [ ['verify-token-options', '#verify-token-options'], ['localization-resource', '/docs/customization/localization'], ['commerce-subscription-item-resource', '/docs/references/javascript/types/commerce-subscription-item-resource'], + ['commerce-money-amount', '/docs/references/javascript/types/commerce-money-amount'], ]; /** diff --git a/packages/backend/src/api/resources/CommercePlan.ts b/packages/backend/src/api/resources/CommercePlan.ts index 8cf2ffbc968..0bf708be820 100644 --- a/packages/backend/src/api/resources/CommercePlan.ts +++ b/packages/backend/src/api/resources/CommercePlan.ts @@ -1,16 +1,12 @@ +import type { CommerceMoneyAmount } from '@clerk/types'; + import { Feature } from './Feature'; import type { CommercePlanJSON } from './JSON'; -export type CommerceMoneyAmount = { - amount: number; - amountFormatted: string; - currency: string; - currencySymbol: string; -}; - /** - * @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 the SDK version to avoid breaking changes. + * The `CommercePlan` object is similar to the [`CommercePlanResource`](/docs/references/javascript/types/commerce-plan-resource) object as it holds information about a plan, as well as methods for managing it. However, the `CommercePlan` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/commerce/get/commerce/plans){{ target: '_blank' }} and is not directly accessible from the Frontend API. + * + * @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 the SDK version to avoid breaking changes. */ export class CommercePlan { constructor( @@ -19,7 +15,7 @@ export class CommercePlan { */ readonly id: string, /** - * The id of the product the plan belongs to. + * The ID of the product the plan belongs to. */ readonly productId: string, /** diff --git a/packages/backend/src/api/resources/CommerceSubscription.ts b/packages/backend/src/api/resources/CommerceSubscription.ts index 8b80c155f35..9c403b10d94 100644 --- a/packages/backend/src/api/resources/CommerceSubscription.ts +++ b/packages/backend/src/api/resources/CommerceSubscription.ts @@ -1,10 +1,12 @@ -import { type CommerceMoneyAmount } from './CommercePlan'; +import { type CommerceMoneyAmount } from '@clerk/types'; + import { CommerceSubscriptionItem } from './CommerceSubscriptionItem'; import type { CommerceSubscriptionJSON } from './JSON'; /** - * @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 the SDK version to avoid breaking changes. + * The `CommerceSubscription` object is similar to the [`CommerceSubscriptionResource`](/docs/references/javascript/types/commerce-subscription-resource) object as it holds information about a subscription, as well as methods for managing it. However, the `CommerceSubscription` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/get/organizations/%7Borganization_id%7D/billing/subscription){{ target: '_blank' }} and is not directly accessible from the Frontend API. + * + * @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 the SDK version to avoid breaking changes. */ export class CommerceSubscription { constructor( @@ -21,19 +23,19 @@ export class CommerceSubscription { */ readonly payerId: string, /** - * Unix timestamp (milliseconds) of creation. + * Unix timestamp (milliseconds) of when the subscription was created. */ readonly createdAt: number, /** - * Unix timestamp (milliseconds) of last update. + * Unix timestamp (milliseconds) of when the subscription was last updated. */ readonly updatedAt: number, /** - * Unix timestamp (milliseconds) when the subscription became active. + * Unix timestamp (milliseconds) of when the subscription became active. */ readonly activeAt: number | null, /** - * Unix timestamp (milliseconds) when the subscription became past due. + * Unix timestamp (milliseconds) of when the subscription became past due. */ readonly pastDueAt: number | null, /** diff --git a/packages/backend/src/api/resources/CommerceSubscriptionItem.ts b/packages/backend/src/api/resources/CommerceSubscriptionItem.ts index 3e57cfa94ea..13e91acbc20 100644 --- a/packages/backend/src/api/resources/CommerceSubscriptionItem.ts +++ b/packages/backend/src/api/resources/CommerceSubscriptionItem.ts @@ -1,11 +1,12 @@ -import type { CommerceMoneyAmountJSON } from '@clerk/types'; +import type { CommerceMoneyAmount, CommerceMoneyAmountJSON } from '@clerk/types'; -import { type CommerceMoneyAmount, CommercePlan } from './CommercePlan'; +import { CommercePlan } from './CommercePlan'; import type { CommerceSubscriptionItemJSON } from './JSON'; /** - * @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 the SDK version to avoid breaking changes. + * The `CommerceSubscriptionItem` object is similar to the [`CommerceSubscriptionItemResource`](/docs/references/javascript/types/commerce-subscription-item-resource) object as it holds information about a subscription item, as well as methods for managing it. However, the `CommerceSubscriptionItem` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/commerce/get/commerce/subscription_items){{ target: '_blank' }} and is not directly accessible from the Frontend API. + * + * @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 the SDK version to avoid breaking changes. */ export class CommerceSubscriptionItem { constructor( @@ -22,14 +23,20 @@ export class CommerceSubscriptionItem { */ readonly planPeriod: 'month' | 'annual', /** - * The start of the current period. + * Unix timestamp (milliseconds) of when the current period starts. */ readonly periodStart: number, /** * The next payment information. */ readonly nextPayment: { + /** + * The amount of the next payment. + */ amount: number; + /** + * Unix timestamp (milliseconds) of when the next payment is scheduled. + */ date: number; } | null, /** @@ -45,27 +52,27 @@ export class CommerceSubscriptionItem { */ readonly planId: string, /** - * The date and time the subscription item was created. + * Unix timestamp (milliseconds) of when the subscription item was created. */ readonly createdAt: number, /** - * The date and time the subscription item was last updated. + * Unix timestamp (milliseconds) of when the subscription item was last updated. */ readonly updatedAt: number, /** - * The end of the current period. + * Unix timestamp (milliseconds) of when the current period ends. */ readonly periodEnd: number | null, /** - * When the subscription item was canceled. + * Unix timestamp (milliseconds) of when the subscription item was canceled. */ readonly canceledAt: number | null, /** - * When the subscription item became past due. + * Unix timestamp (milliseconds) of when the subscription item became past due. */ readonly pastDueAt: number | null, /** - * When the subscription item ended. + * Unix timestamp (milliseconds) of when the subscription item ended. */ readonly endedAt: number | null, /** diff --git a/packages/backend/src/api/resources/Feature.ts b/packages/backend/src/api/resources/Feature.ts index f1fa1d48774..787f9bb8da4 100644 --- a/packages/backend/src/api/resources/Feature.ts +++ b/packages/backend/src/api/resources/Feature.ts @@ -1,11 +1,31 @@ import type { FeatureJSON } from './JSON'; +/** + * The `Feature` object represents a feature of a subscription plan. + * + * @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 the SDK version to avoid breaking changes. + */ export class Feature { constructor( + /** + * The unique identifier for the feature. + */ readonly id: string, + /** + * The name of the feature. + */ readonly name: string, + /** + * The description of the feature. + */ readonly description: string, + /** + * The URL-friendly identifier of the feature. + */ readonly slug: string, + /** + * The URL of the feature's avatar image. + */ readonly avatarUrl: string, ) {} diff --git a/packages/backend/src/api/resources/index.ts b/packages/backend/src/api/resources/index.ts index f4be508678d..855fb43df45 100644 --- a/packages/backend/src/api/resources/index.ts +++ b/packages/backend/src/api/resources/index.ts @@ -60,6 +60,7 @@ export * from './Web3Wallet'; export * from './CommercePlan'; export * from './CommerceSubscription'; export * from './CommerceSubscriptionItem'; +export * from './Feature'; export type { EmailWebhookEvent, diff --git a/packages/backend/src/index.ts b/packages/backend/src/index.ts index 70a0f7fa064..5023e0e8df5 100644 --- a/packages/backend/src/index.ts +++ b/packages/backend/src/index.ts @@ -119,6 +119,7 @@ export type { Domain, EmailAddress, ExternalAccount, + Feature, Instance, InstanceRestrictions, InstanceSettings, diff --git a/packages/types/src/commerce.ts b/packages/types/src/commerce.ts index 0495f9dd135..59973af134f 100644 --- a/packages/types/src/commerce.ts +++ b/packages/types/src/commerce.ts @@ -4,6 +4,9 @@ import type { ClerkResource } from './resource'; import type { CommerceFeatureJSONSnapshot } from './snapshots'; type WithOptionalOrgType = T & { + /** + * The organization ID to perform the request on. + */ orgId?: string; }; @@ -141,12 +144,9 @@ export type ForPayerType = 'organization' | 'user'; export type CommerceSubscriptionStatus = 'active' | 'ended' | 'upcoming' | 'past_due'; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The billing period for the plan. + * + * @inline */ export type CommerceSubscriptionPlanPeriod = 'month' | 'annual'; @@ -365,61 +365,40 @@ export interface CommercePlanResource extends ClerkResource { } /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The `CommerceFeatureResource` type represents a feature of a subscription plan. + * + * @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 the SDK version to avoid breaking changes. */ export interface CommerceFeatureResource extends ClerkResource { + /** + * The unique identifier for the feature. + */ id: string; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The display name of the feature. */ name: string; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * A short description of what the feature provides. */ description: string; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * A unique, URL-friendly identifier for the feature. */ slug: string; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The URL of the feature's avatar image. */ avatarUrl: string; + /** + * @hidden + */ __internal_toSnapshot: () => CommerceFeatureJSONSnapshot; } /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The status of a payment source. + * @inline */ export type CommercePaymentSourceStatus = 'active' | 'expired' | 'disconnected'; @@ -513,86 +492,55 @@ export type RemovePaymentSourceParams = WithOptionalOrgType; export type MakeDefaultPaymentSourceParams = 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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The `CommercePaymentSourceResource` type represents a payment source for a checkout session. + * + * @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 the SDK version and the clerk-js version to avoid breaking changes. */ export interface CommercePaymentSourceResource extends ClerkResource { + /** + * The unique identifier for the payment method. + */ id: string; + /** + * The last four digits of the payment method. + */ last4: string; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The type of payment method. For example, `'card'` or `'bank_account'`. */ paymentMethod: string; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The brand or type of card. For example, `'visa'` or `'mastercard'`. */ cardType: string; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * Whether the payment method is set as the default for the account. */ isDefault: boolean; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * Whether the payment method can be removed by the user. */ isRemovable: boolean; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The current status of the payment method. */ status: CommercePaymentSourceStatus; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The type of digital wallet, if applicable. For example, `'apple_pay'`, or `'google_pay'`. */ walletType: string | undefined; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * A function that removes this payment source from the account. Accepts the following parameters: + * - `orgId?` (`string`): The ID of the organization to remove the payment source from. + * @param params - The parameters for the remove operation. + * @returns A promise that resolves to a `DeletedObjectResource` object. */ remove: (params?: RemovePaymentSourceParams) => Promise; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * A function that sets this payment source as the default for the account. Accepts the following parameters: + * - `orgId?` (`string`): The ID of the organization to set as the default. + * @param params - The parameters for the make default operation. + * @returns A promise that resolves to `null`. */ makeDefault: (params?: MakeDefaultPaymentSourceParams) => Promise; } @@ -829,30 +777,17 @@ export interface CommerceStatementResource extends ClerkResource { } /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The `CommerceStatementGroup` type represents a group of payment items within a statement. + * + * @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 the SDK version and the clerk-js version to avoid breaking changes. */ export interface CommerceStatementGroup { /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The date and time when this group of payment items was created or last updated. */ timestamp: Date; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * An array of payment resources that belong to this group. */ items: CommercePaymentResource[]; } @@ -1149,124 +1084,65 @@ export interface CommerceSubscriptionResource extends ClerkResource { } /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The `CommerceMoneyAmount` type represents a monetary value with currency information. + * + * @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 the SDK version and the clerk-js version to avoid breaking changes. */ export interface CommerceMoneyAmount { /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The raw amount as a number, usually in the smallest unit of the currency (like cents for USD). For example, `1000` for $10.00. */ amount: number; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The amount as a formatted string. For example, `10.00` for $10.00. */ amountFormatted: string; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The ISO currency code for this amount. For example, `USD`. */ currency: string; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The symbol for the currency. For example, `$`. */ currencySymbol: string; } /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The `CommerceCheckoutTotals` type represents the total costs, taxes, and other pricing details for a checkout session. + * + * @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 the SDK version and the clerk-js version to avoid breaking changes. */ export interface CommerceCheckoutTotals { /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The price of the items or plan before taxes, credits, or discounts are applied. */ subtotal: CommerceMoneyAmount; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The total amount for the checkout, including taxes and after credits/discounts are applied. This is the final amount due. */ grandTotal: CommerceMoneyAmount; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The amount of tax included in the checkout. */ taxTotal: CommerceMoneyAmount; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The amount that needs to be immediately paid to complete the checkout. */ totalDueNow: CommerceMoneyAmount; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * Any credits (like account balance or promo credits) that are being applied to the checkout. */ credit: CommerceMoneyAmount; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * Any outstanding amount from previous unpaid invoices that is being collected as part of the checkout. */ pastDue: CommerceMoneyAmount; } /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The `CommerceStatementTotals` type represents the total costs, taxes, and other pricing details for a statement. + * + * @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 the SDK version and the clerk-js version to avoid breaking changes. */ // eslint-disable-next-line @typescript-eslint/no-empty-object-type export interface CommerceStatementTotals extends Omit {} @@ -1301,173 +1177,90 @@ 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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The `confirm()` method accepts the following parameters. **Only one of `paymentSourceId`, `paymentToken`, or `useTestCard` should be provided.** + * + * @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 the SDK version and the clerk-js version to avoid breaking changes. */ export type ConfirmCheckoutParams = | { /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The ID of a saved payment source to use for this checkout. */ paymentSourceId?: string; } | { /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * A token representing payment details, usually from a payment form. **Requires** `gateway` to be provided. */ paymentToken?: string; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The payment gateway to use. For example, `'stripe'` or `'paypal'`. **Required** if `paymentToken` or `useTestCard` is provided. */ gateway?: PaymentGateway; } | { /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The payment gateway to use. For example, `'stripe'` or `'paypal'`. **Required** if `paymentToken` or `useTestCard` is provided. */ gateway?: PaymentGateway; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * If true, uses a test card for the checkout. **Requires** `gateway` to be provided. */ useTestCard?: boolean; }; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The `CommerceCheckoutResource` type represents information about a checkout session. + * + * @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 the SDK version and the clerk-js version to avoid breaking changes. */ export interface CommerceCheckoutResource extends ClerkResource { + /** + * The unique identifier for the checkout session. + */ id: string; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * A client secret from an external payment provider (such as Stripe) used to complete the payment on the client-side. */ externalClientSecret: string; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The identifier for the external payment gateway used for this checkout session. */ externalGatewayId: string; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The payment source being used for the checkout, such as a credit card or bank account. */ paymentSource?: CommercePaymentSourceResource; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The subscription plan details for the checkout. */ plan: CommercePlanResource; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The billing period for the plan. */ planPeriod: CommerceSubscriptionPlanPeriod; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * Unix timestamp (milliseconds) of when the current period starts. */ planPeriodStart?: number; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The current status of the checkout session. */ status: 'needs_confirmation' | 'completed'; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * The total costs, taxes, and other pricing details for the checkout. */ totals: CommerceCheckoutTotals; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](#confirm) */ confirm: (params: ConfirmCheckoutParams) => Promise; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * Whether the plan change will take effect immediately after checkout. */ isImmediatePlanChange: boolean; /** - * @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 the SDK version and the clerk-js version to a specific version to avoid breaking changes. - * @example - * ```tsx - * - * ``` + * Unix timestamp (milliseconds) of when the free trial ends. */ freeTrialEndsAt: Date | null; /**