chore(types): Add notice for experimental commerce apis (#6285)

Author: panteliselef

.changeset/curly-rules-fall.md

@@ -0,0 +1,5 @@
+---
+'@clerk/types': patch
+---
+
+Add notice for upcoming/possible breaking changes in commerce related APIs.

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -5,6 +5,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/act-claim.mdx",
   "types/act-jwt-claim.mdx",
   "types/active-session-resource.mdx",
+  "types/add-payment-source-params.mdx",
+  "types/cancel-subscription-params.mdx",
   "types/check-authorization-fn.mdx",
   "types/check-authorization-from-session-claims.mdx",
   "types/check-authorization-params-from-session-claims.mdx",
@@ -19,15 +21,61 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/clerk-resource.mdx",
   "types/clerk-status.mdx",
   "types/clerk.mdx",
+  "types/commerce-billing-namespace.mdx",
+  "types/commerce-checkout-json.mdx",
+  "types/commerce-checkout-resource.mdx",
+  "types/commerce-checkout-totals-json.mdx",
+  "types/commerce-checkout-totals.mdx",
+  "types/commerce-feature-json.mdx",
+  "types/commerce-feature-resource.mdx",
+  "types/commerce-initialized-payment-source-json.mdx",
+  "types/commerce-initialized-payment-source-resource.mdx",
+  "types/commerce-money-json.mdx",
+  "types/commerce-money.mdx",
+  "types/commerce-payment-charge-type.mdx",
+  "types/commerce-payment-json.mdx",
+  "types/commerce-payment-resource.mdx",
+  "types/commerce-payment-source-json.mdx",
+  "types/commerce-payment-source-methods.mdx",
+  "types/commerce-payment-source-resource.mdx",
+  "types/commerce-payment-source-status.mdx",
+  "types/commerce-payment-status.mdx",
+  "types/commerce-plan-json.mdx",
+  "types/commerce-plan-resource.mdx",
+  "types/commerce-product-json.mdx",
+  "types/commerce-product-resource.mdx",
+  "types/commerce-statement-group-json.mdx",
+  "types/commerce-statement-group.mdx",
+  "types/commerce-statement-json.mdx",
+  "types/commerce-statement-resource.mdx",
+  "types/commerce-statement-status.mdx",
+  "types/commerce-statement-totals-json.mdx",
+  "types/commerce-statement-totals.mdx",
+  "types/commerce-subscriber-type.mdx",
+  "types/commerce-subscription-json.mdx",
+  "types/commerce-subscription-plan-period.mdx",
+  "types/commerce-subscription-resource.mdx",
+  "types/commerce-subscription-status.mdx",
+  "types/confirm-checkout-params.mdx",
+  "types/create-checkout-params.mdx",
   "types/create-organization-params.mdx",
   "types/element-object-key.mdx",
   "types/elements-config.mdx",
+  "types/get-payment-attempts-params.mdx",
+  "types/get-payment-sources-params.mdx",
+  "types/get-plans-params.mdx",
+  "types/get-statements-params.mdx",
+  "types/get-subscriptions-params.mdx",
   "types/get-token.mdx",
   "types/id-selectors.mdx",
+  "types/initialize-payment-source-params.mdx",
+  "types/internal_checkout-props.mdx",
+  "types/internal_plan-details-props.mdx",
   "types/jwt-claims.mdx",
   "types/jwt-header.mdx",
   "types/legacy-redirect-props.mdx",
   "types/localization-resource.mdx",
+  "types/make-default-payment-source-params.mdx",
   "types/multi-domain-and-or-proxy.mdx",
   "types/organization-custom-role-key.mdx",
   "types/organization-domain-resource.mdx",
@@ -44,11 +92,13 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/organizations-jwt-claim.mdx",
   "types/override.mdx",
   "types/path-value.mdx",
+  "types/payment-gateway.mdx",
   "types/pending-session-options.mdx",
   "types/pending-session-resource.mdx",
   "types/protect-props.mdx",
   "types/record-to-path.mdx",
   "types/redirect-options.mdx",
+  "types/remove-payment-source-params.mdx",
   "types/reverification-config.mdx",
   "types/saml-strategy.mdx",
   "types/sdk-metadata.mdx",

packages/types/src/clerk.ts

@@ -184,7 +184,16 @@ export interface Clerk {
   /** Current User. */
   user: UserResource | null | undefined;
 
-  /** Billing Object */
+  /**
+   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+   * @see https://clerk.com/docs/billing/overview
+   *
+   * It is advised to pin the SDK version and the clerk-js version to a specific version to avoid breaking changes.
+   * @example
+   * ```tsx
+   * <ClerkProvider clerkJsVersion="x.x.x" />
+   * ```
+   */
   billing: CommerceBillingNamespace;
 
   telemetry: TelemetryCollector | undefined;
@@ -1724,6 +1733,16 @@ export type RevokeAPIKeyParams = {
   revocationReason?: 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.
+ * @see https://clerk.com/docs/billing/overview
+ *
+ * It is advised to pin the SDK version and the clerk-js version to a specific version to avoid breaking changes.
+ * @example
+ * ```tsx
+ * <ClerkProvider clerkJsVersion="x.x.x" />
+ * ```
+ */
 export type __internal_CheckoutProps = {
   appearance?: CheckoutTheme;
   planId?: string;
@@ -1740,6 +1759,16 @@ export type __internal_CheckoutProps = {
   onClose?: () => void;
 };
 
+/**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * @see https://clerk.com/docs/billing/overview
+ *
+ * It is advised to pin the SDK version and the clerk-js version to a specific version to avoid breaking changes.
+ * @example
+ * ```tsx
+ * <ClerkProvider clerkJsVersion="x.x.x" />
+ * ```
+ */
 export type __internal_PlanDetailsProps = {
   appearance?: PlanDetailTheme;
   plan?: CommercePlanResource;