docs(backend): clarify domain API documentation

.changeset/two-aliens-build.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Clarify domain API documentation and deletion parameter names. The active domain cannot be deleted.

packages/backend/src/api/endpoints/DomainApi.ts

@@ -12,7 +12,7 @@ export type AddDomainParams = {
    * The new domain name. For development instances, can contain the port, e.g., `myhostname:3000`. For production instances, must be a valid FQDN, e.g., `mysite.com`. Cannot contain protocol scheme.
    */
   name: string;
-  /** Whether the new domain is a satellite domain. Only `true` is accepted at the moment. */
+  /** Whether the new domain is a satellite domain. */
   is_satellite: boolean;
   /** The proxy URL for the domain. Applicable only to production instances. */
   proxy_url?: string | null;
@@ -70,25 +70,25 @@ export class DomainAPI extends AbstractAPI {
   }
 
   /**
-   * Deletes a satellite domain for the instance. It is currently not possible to delete the instance's primary domain.
-   * @param satelliteDomainId - The ID of the satellite domain to delete.
+   * Deletes a domain for the instance. The active domain cannot be deleted.
+   * @param domainId - The ID of the domain to delete.
    * @returns The [`DeletedObject`](https://clerk.com/docs/reference/backend/types/deleted-object).
    */
-  public async delete(satelliteDomainId: string) {
-    return this.deleteDomain(satelliteDomainId);
+  public async delete(domainId: string) {
+    return this.deleteDomain(domainId);
   }
 
   /**
-   * Deletes a satellite domain for the instance.
-   * @param satelliteDomainId - The ID of the satellite domain to delete.
+   * Deletes a domain for the instance. The active domain cannot be deleted.
+   * @param domainId - The ID of the domain to delete.
    * @returns The [`DeletedObject`](https://clerk.com/docs/reference/backend/types/deleted-object).
    * @deprecated Use `delete()` instead.
    */
-  public async deleteDomain(satelliteDomainId: string) {
-    this.requireId(satelliteDomainId);
+  public async deleteDomain(domainId: string) {
+    this.requireId(domainId);
     return this.request<DeletedObject>({
       method: 'DELETE',
-      path: joinPaths(basePath, satelliteDomainId),
+      path: joinPaths(basePath, domainId),
     });
   }
 }