@scalekit-sdk/node 2.1.7 → 2.1.8

package/lib/directory.js

@@ -11,6 +11,21 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 const protobuf_1 = require("@bufbuild/protobuf");
 const directories_connect_1 = require("./pkg/grpc/scalekit/v1/directories/directories_connect");
+/**
+ * Client for managing SCIM directory synchronization.
+ *
+ * Directories represent SCIM connections that automatically sync users and groups from an
+ * organization's identity provider (Okta, Azure AD, Google Workspace, etc.) to your application.
+ * Use this client to retrieve synchronized user/group data, manage directory settings, and
+ * monitor sync status.
+ *
+ * @example
+ * const scalekitClient = new ScalekitClient(envUrl, clientId, clientSecret);
+ * const directoryClient = scalekitClient.directory;
+ *
+ * @see {@link https://docs.scalekit.com/apis/#tag/directory | Directory API Documentation}
+ * @see {@link https://docs.scalekit.com/directory/scim/quickstart/ | SCIM Directory Sync Guide}
+ */
 class DirectoryClient {
     constructor(grpcConncet, coreClient) {
         this.grpcConncet = grpcConncet;
@@ -18,58 +33,203 @@ class DirectoryClient {
         this.client = this.grpcConncet.createClient(directories_connect_1.DirectoryService);
     }
     /**
-     * List directories for an organization
-     * @param {string} organizationId The organization id
-     * @returns {Promise<ListDirectoriesResponse>} Returns the list of directories
+     * Retrieves all SCIM directories configured for an organization.
+     *
+     * Lists all directory sync connections that have been set up for the organization. Each directory
+     * represents a SCIM integration with an identity provider (Okta, Azure AD, Google Workspace, etc.)
+     * that automatically syncs users and groups. Use this to view directory configurations, check sync
+     * status, and manage directory integrations.
+     *
+     * @param {string} organizationId - The organization ID to list directories for (format: "org_...")
+     *
+     * @returns {Promise<ListDirectoriesResponse>} Response containing:
+     *   - directories: Array of directory objects with:
+     *     - id: Unique directory identifier
+     *     - organizationId: Parent organization ID
+     *     - provider: Identity provider name (e.g., "okta", "azure_ad", "google")
+     *     - enabled: Whether directory sync is active
+     *     - status: Current synchronization status
+     *     - lastSyncTime: When the last sync occurred
+     *     - userCount: Number of synced users
+     *     - groupCount: Number of synced groups
+     *
+     * @throws {Error} If the organization is not found
+     *
+     * @example
+     * // List all directories for an organization
+     * const response = await scalekitClient.directory.listDirectories('org_123456');
+     *
+     * console.log(`Found ${response.directories.length} directories`);
+     * response.directories.forEach(dir => {
+     *   console.log(`- ${dir.provider}: ${dir.enabled ? 'Active' : 'Inactive'}`);
+     *   console.log(`  Users: ${dir.userCount}, Groups: ${dir.groupCount}`);
+     * });
+     *
+     * @example
+     * // Check if organization has any active directories
+     * const response = await scalekitClient.directory.listDirectories('org_123456');
+     * const hasActiveDirectory = response.directories.some(dir => dir.enabled);
+     *
+     * if (hasActiveDirectory) {
+     *   console.log('Directory sync is enabled for this organization');
+     * } else {
+     *   console.log('No active directory sync');
+     * }
+     *
+     *
+     * @see {@link https://docs.scalekit.com/apis/#tag/directory | List Directories API}
+     * @see {@link getDirectory} - Get details of a specific directory
+     * @see {@link enableDirectory} - Enable directory sync
+     * @see {@link disableDirectory} - Disable directory sync
      */
     listDirectories(organizationId) {
         return __awaiter(this, void 0, void 0, function* () {
-            return this.coreClient.connectExec(this.client.listDirectories, { organizationId });
+            return this.coreClient.connectExec(this.client.listDirectories, {
+                organizationId,
+            });
         });
     }
     /**
-     * Get a directory for an organization
-     * @param {string} organizationId The organization id
-     * @param {string} directoryId The directory id
-     * @returns {Promise<GetDirectoryResponse>} Returns the directory
+     * Retrieves comprehensive details about a specific SCIM directory.
+     *
+     * Fetches complete configuration and status information for a directory, including provider settings,
+     * synchronization status, user/group counts, and metadata. Use this to view directory configuration,
+     * monitor sync health, verify setup, or display directory details in admin interfaces.
+     *
+     * @param {string} organizationId - The organization ID that owns the directory (format: "org_...")
+     * @param {string} directoryId - The directory identifier to retrieve (format: "dir_...")
+     *
+     * @returns {Promise<GetDirectoryResponse>} Response containing:
+     *   - directory: Complete directory object with:
+     *     - id: Unique directory identifier
+     *     - organizationId: Parent organization ID
+     *     - provider: Identity provider name (e.g., "okta", "azure_ad", "google")
+     *     - enabled: Whether directory sync is active
+     *     - status: Current synchronization status
+     *     - scimBaseUrl: SCIM endpoint URL
+     *     - scimToken: Authentication token (masked)
+     *     - lastSyncTime: Timestamp of last successful sync
+     *     - nextSyncTime: Scheduled time for next sync
+     *     - userCount: Number of synced users
+     *     - groupCount: Number of synced groups
+     *     - createTime: When directory was created
+     *     - updateTime: When directory was last updated
+     *
+     * @throws {Error} If the organization or directory is not found
+     *
+     * @example
+     * // Get directory details
+     * const response = await scalekitClient.directory.getDirectory(
+     *   'org_123456',
+     *   'dir_abc123'
+     * );
+     *
+     * const dir = response.directory;
+     * console.log('Provider:', dir.provider);
+     * console.log('Status:', dir.enabled ? 'Active' : 'Inactive');
+     * console.log('Last sync:', dir.lastSyncTime);
+     * console.log('Users:', dir.userCount);
+     * console.log('Groups:', dir.groupCount);
+     *
+     *
+     * @see {@link https://docs.scalekit.com/apis/#tag/directory | Get Directory API}
+     * @see {@link getPrimaryDirectoryByOrganizationId} - List the first directory in an Organization.
+     *                                                  - Useful utility API if you don't know the directory ID but only have an organizationID.
+     * @see {@link listDirectoryUsers} - List users in this directory
+     * @see {@link listDirectoryGroups} - List groups in this directory
      */
     getDirectory(organizationId, directoryId) {
         return __awaiter(this, void 0, void 0, function* () {
-            return this.coreClient.connectExec(this.client.getDirectory, { organizationId, id: directoryId });
+            return this.coreClient.connectExec(this.client.getDirectory, {
+                organizationId,
+                id: directoryId,
+            });
         });
     }
     /**
-     * Get a directory for an organization
-     * @param {string} organizationId The organization id
-     * @returns {Promise<Directory>} Returns the directory
+     * Retrieves the primary (first) directory for an organization.
+     *
+     * This is a convenience method that fetches the first directory from the organization's list
+     * of directories. Most organizations have a single directory, making this useful for quickly
+     * accessing directory data without needing to know the specific directory ID. If the organization
+     * has multiple directories, this returns the first one.
+     *
+     * @param {string} organizationId - The organization ID to get the primary directory for (format: "org_...")
+     *
+     * @returns {Promise<Directory>} The first directory object for the organization
+     *
+     * @throws {Error} When the organization has no directories configured
+     *
+     * @example
+     * // Get primary directory for an organization
+     * try {
+     *   const directory = await scalekitClient.directory.getPrimaryDirectoryByOrganizationId('org_123456');
+     *
+     *   console.log('Primary Directory:', directory.provider);
+     *   console.log('Users:', directory.userCount);
+     *   console.log('Groups:', directory.groupCount);
+     * } catch (error) {
+     *   console.log('No directory configured for this organization');
+     * }
+     *
+     *
+     * @see {@link listDirectories} - List all directories for an organization
+     * @see {@link getDirectory} - Get a specific directory by ID
+     * @see {@link listDirectoryUsers} - List users in the directory
      */
     getPrimaryDirectoryByOrganizationId(organizationId) {
         return __awaiter(this, void 0, void 0, function* () {
             const directories = yield this.listDirectories(organizationId);
             if (!directories || directories.directories.length === 0) {
-                return Promise.reject('directory does not exist for organization');
+                return Promise.reject("directory does not exist for organization");
             }
             return directories.directories[0];
         });
     }
     /**
-     * List users in a directory for an organization
-     * @param {string} organizationId The organization id
-     * @param {string} directoryId The directory id
-     * @param {object} options The options to list directory users
-     * @param {number} options.pageSize The page size
-     * @param {string} options.pageToken The page token
-     * @param {boolean} options.includeDetail Include detail
-     * @param {string} options.directoryGroupId The directory group id
-     * @param {string} options.updatedAfter The updated after
-     * @returns {Promise<ListDirectoryUsersResponse>} Returns the list of directory users
+     * Lists users synchronized from an identity provider via SCIM directory sync.
+     *
+     * Retrieves all users that have been synced from the organization's IdP to your application.
+     * This includes user profile information, group memberships, and sync status. Use this to
+     * display organization users, implement user search, or track provisioning/deprovisioning.
+     *
+     * @param {string} organizationId - The organization ID
+     * @param {string} directoryId - The directory ID
+     * @param {object} [options] - Optional filtering and pagination parameters
+     * @param {number} [options.pageSize] - Number of users per page (max: 100)
+     * @param {string} [options.pageToken] - Token for next page from previous response
+     * @param {boolean} [options.includeDetail] - Include full user profile details
+     * @param {string} [options.directoryGroupId] - Filter users by group membership
+     * @param {string} [options.updatedAfter] - ISO 8601 timestamp to fetch only users updated after this time
+     *
+     * @returns {Promise<ListDirectoryUsersResponse>} Response containing:
+     *   - users: Array of directory user objects with profiles and attributes
+     *   - nextPageToken: Token for retrieving the next page
+     *   - totalSize: Total number of users in the directory
+     *
+     * @example
+     * // List all directory users with pagination
+     * const response = await scalekitClient.directory.listDirectoryUsers(
+     *   'org_123456',
+     *   'dir_abc123',
+     *   { pageSize: 50 }
+     * );
+     *
+     * console.log(`Found ${response.totalSize} users`);
+     * response.users.forEach(user => {
+     *   console.log(`- ${user.email} (${user.firstName} ${user.lastName})`);
+     * });
+     *
+     * @see {@link https://docs.scalekit.com/apis/#tag/directory | List Directory Users API}
+     * @see {@link listDirectoryGroups} - List directory groups
+     * @see {@link listDirectories} - List all directories for an organization
      */
     listDirectoryUsers(organizationId, directoryId, options) {
         return __awaiter(this, void 0, void 0, function* () {
             let requestOptions = {};
             if (options) {
                 requestOptions = Object.assign(Object.assign({}, options), (options.updatedAfter && {
-                    updatedAfter: protobuf_1.Timestamp.fromDate(new Date(options.updatedAfter))
+                    updatedAfter: protobuf_1.Timestamp.fromDate(new Date(options.updatedAfter)),
                 }));
             }
             return this.coreClient.connectExec(this.client.listDirectoryUsers, Object.assign({ organizationId,
@@ -77,22 +237,68 @@ class DirectoryClient {
         });
     }
     /**
-     * List groups in a directory for an organization
-     * @param {string} organizationId The organization id
-     * @param {string} directoryId The directory id
-     * @param {object} options The options to list directory groups
-     * @param {number} options.pageSize The page size
-     * @param {string} options.pageToken The page token
-     * @param {boolean} options.includeDetail Include detail
-     * @param {string} options.updatedAfter The updated after
-     * @returns {Promise<ListDirectoryGroupsResponse>} Returns the list of directory groups
+     * Retrieves groups synchronized from an identity provider via SCIM directory sync.
+     *
+     * Fetches all groups that have been synced from the organization's IdP to your application.
+     * Groups typically represent teams, departments, or organizational units. Use this to display
+     * group hierarchies, implement group-based access control, manage group memberships, or track
+     * organizational structure changes.
+     *
+     * @param {string} organizationId - The organization ID (format: "org_...")
+     * @param {string} directoryId - The directory ID (format: "dir_...")
+     * @param {object} [options] - Optional filtering and pagination parameters
+     * @param {number} [options.pageSize] - Number of groups per page (max: 30, default: 10)
+     * @param {string} [options.pageToken] - Token for next page from previous response
+     * @param {boolean} [options.includeDetail] - Include full group details and member lists
+     * @param {string} [options.updatedAfter] - ISO 8601 timestamp to fetch only groups updated after this time
+     *
+     * @returns {Promise<ListDirectoryGroupsResponse>} Response containing:
+     *   - groups: Array of directory group objects with:
+     *     - id: Group identifier
+     *     - displayName: Group name
+     *     - description: Group description
+     *     - members: Array of member user IDs (when includeDetail is true)
+     *     - attributes: Custom group attributes
+     *     - updateTime: When the group was last updated
+     *   - nextPageToken: Token for retrieving the next page
+     *   - totalSize: Total number of groups in the directory
+     *
+     * @example
+     * // List all directory groups with pagination
+     * const response = await scalekitClient.directory.listDirectoryGroups(
+     *   'org_123456',
+     *   'dir_abc123',
+     *   { pageSize: 30 }
+     * );
+     *
+     * console.log(`Found ${response.totalSize} groups`);
+     * response.groups.forEach(group => {
+     *   console.log(`- ${group.displayName}`);
+     *   if (group.description) console.log(`  ${group.description}`);
+     * });
+     *
+     * @example
+     * // Get groups with full member details
+     * const response = await scalekitClient.directory.listDirectoryGroups(
+     *   'org_123456',
+     *   'dir_abc123',
+     *   { includeDetail: true }
+     * );
+     *
+     * response.groups.forEach(group => {
+     *   console.log(`${group.displayName}: ${group.members?.length || 0} members`);
+     * });
+     *
+     * @see {@link https://docs.scalekit.com/apis/#tag/directory | List Directory Groups API}
+     * @see {@link listDirectoryUsers} - List directory users
+     * @see {@link getDirectory} - Get directory details
      */
     listDirectoryGroups(organizationId, directoryId, options) {
         return __awaiter(this, void 0, void 0, function* () {
             let requestOptions = {};
             if (options) {
                 requestOptions = Object.assign(Object.assign({}, options), (options.updatedAfter && {
-                    updatedAfter: protobuf_1.Timestamp.fromDate(new Date(options.updatedAfter))
+                    updatedAfter: protobuf_1.Timestamp.fromDate(new Date(options.updatedAfter)),
                 }));
             }
             return this.coreClient.connectExec(this.client.listDirectoryGroups, Object.assign({ organizationId,
@@ -100,25 +306,83 @@ class DirectoryClient {
         });
     }
     /**
-     * Enable a directory for an organization
-     * @param {string} organizationId The organization id
-     * @param {string} directoryId The directory id
-     * @returns {Promise<ToggleDirectoryResponse>} Returns the directory enable response
+     * Enables SCIM directory synchronization for an organization.
+     *
+     * Activates automatic user and group synchronization from the organization's identity provider.
+     * Once enabled, users and groups from the IdP will be synced to your application, and any changes
+     * in the IdP (additions, updates, deletions) will be automatically reflected. This is essential
+     * for implementing automated user provisioning and deprovisioning.
+     *
+     * @param {string} organizationId - The organization ID (format: "org_...")
+     * @param {string} directoryId - The directory ID to enable (format: "dir_...")
+     *
+     * @returns {Promise<ToggleDirectoryResponse>} Response containing:
+     *   - directory: The updated directory object with enabled status set to true
+     *
+     * @throws {Error} If the organization or directory is not found
+     * @throws {Error} If the directory configuration is incomplete or invalid
+     *
+     * @example
+     * // Enable directory sync
+     * const response = await scalekitClient.directory.enableDirectory(
+     *   'org_123456',
+     *   'dir_abc123'
+     * );
+     *
+     * console.log('Directory enabled:', response.directory.enabled); // true
+     * console.log('Sync will start automatically');
+     *
+     * @see {@link https://docs.scalekit.com/apis/#tag/directory | Enable Directory API}
+     * @see {@link disableDirectory} - Disable directory sync
+     * @see {@link getDirectory} - Check directory status
+     * @see {@link listDirectoryUsers} - View synced users after enabling
      */
     enableDirectory(organizationId, directoryId) {
         return __awaiter(this, void 0, void 0, function* () {
-            return this.coreClient.connectExec(this.client.enableDirectory, { organizationId, id: directoryId });
+            return this.coreClient.connectExec(this.client.enableDirectory, {
+                organizationId,
+                id: directoryId,
+            });
         });
     }
     /**
-     * Disable a directory for an organization
-     * @param {string} organizationId The organization id
-     * @param {string} directoryId The directory id
-     * @returns {Promise<ToggleDirectoryResponse>} Returns the directory disable response
+     * Disables SCIM directory synchronization for an organization.
+     *
+     * Stops automatic user and group synchronization from the organization's identity provider.
+     * When disabled, no new updates will be received from the IdP, but existing synced users and
+     * groups remain in your application. This is useful for temporarily pausing sync during maintenance,
+     * troubleshooting, or when migrating to a different directory provider. Does not delete existing data.
+     *
+     * @param {string} organizationId - The organization ID (format: "org_...")
+     * @param {string} directoryId - The directory ID to disable (format: "dir_...")
+     *
+     * @returns {Promise<ToggleDirectoryResponse>} Response containing:
+     *   - directory: The updated directory object with enabled status set to false
+     *
+     * @throws {Error} If the organization or directory is not found
+     *
+     * @example
+     * // Disable directory sync
+     * const response = await scalekitClient.directory.disableDirectory(
+     *   'org_123456',
+     *   'dir_abc123'
+     * );
+     *
+     * console.log('Directory disabled:', !response.directory.enabled); // true
+     * console.log('Existing users and groups are preserved');
+     *
+     *
+     * @see {@link https://docs.scalekit.com/apis/#tag/directory | Disable Directory API}
+     * @see {@link enableDirectory} - Enable directory sync
+     * @see {@link getDirectory} - Check directory status
+     * @see {@link listDirectories} - List all directories
      */
     disableDirectory(organizationId, directoryId) {
         return __awaiter(this, void 0, void 0, function* () {
-            return this.coreClient.connectExec(this.client.disableDirectory, { organizationId, id: directoryId });
+            return this.coreClient.connectExec(this.client.disableDirectory, {
+                organizationId,
+                id: directoryId,
+            });
         });
     }
 }

package/lib/directory.js.map

@@ -1 +1 @@
-{"version":3,"file":"directory.js","sourceRoot":"","sources":["../src/directory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"directory.js","sourceRoot":"","sources":["../src/directory.ts"],"names":[],"mappings":"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"}

package/lib/domain.d.ts

@@ -1,35 +1,183 @@
-import GrpcConnect from './connect';
-import CoreClient from './core';
-import { CreateDomainResponse, GetDomainResponse, ListDomainResponse, DomainType } from './pkg/grpc/scalekit/v1/domains/domains_pb';
-import { Empty } from '@bufbuild/protobuf';
+import GrpcConnect from "./connect";
+import CoreClient from "./core";
+import { CreateDomainResponse, GetDomainResponse, ListDomainResponse, DomainType } from "./pkg/grpc/scalekit/v1/domains/domains_pb";
+import { Empty } from "@bufbuild/protobuf";
+/**
+ * Client for managing domains for organizations.
+ *
+ * Domains enable automatic organization identification during SSO flows based on user email addresses.
+ * You can configure domains as ORGANIZATION_DOMAIN (for SSO routing) or ALLOWED_EMAIL_DOMAIN
+ * (for restricting which email domains can automatically join an organization).
+ *
+ * @example
+ * const scalekitClient = new ScalekitClient(envUrl, clientId, clientSecret);
+ * const domainClient = scalekitClient.domain;
+ *
+ * @see {@link https://docs.scalekit.com/apis/#tag/domains | Domain API Documentation}
+ */
 export default class DomainClient {
     private readonly grpcConncet;
     private readonly coreClient;
     private client;
     constructor(grpcConncet: GrpcConnect, coreClient: CoreClient);
     /**
-     * Create a domain for an organization with the given name. Optionally, you can provide an external id.
-     * @param {string} organizationId  The organization id
-     * @param {string} name The domain name
-     * @param {object} options The options to create a domain
-     * @param {DomainType | string} options.domainType The type of domain (ALLOWED_EMAIL_DOMAIN or ORGANIZATION_DOMAIN)
-     * @returns {Promise<CreateDomainResponse>} The created domain
-    */
+     * Adds a new domain configuration to an organization for SSO routing or user suggestions.
+     *
+     * Domains serve two purposes based on their type:
+     * - **ORGANIZATION_DOMAIN**: Used to identify the SSO connection for the organization. When users
+     *   authenticate with email addresses from this domain, they're automatically routed to the
+     *   organization's SSO provider.
+     * - **ALLOWED_EMAIL_DOMAIN**: Enables users to join the organization with automatic suggestions
+     *   in the organization switcher during signup/login.
+     *
+     * Note: Public disposable domains (gmail.com, outlook.com, etc.) are automatically blocked for security.
+     *
+     * @param {string} organizationId - The organization ID (format: "org_...")
+     * @param {string} name - The domain name (e.g., "acme.com", "example.org")
+     * @param {object} [options] - Optional domain configuration
+     * @param {DomainType | string} [options.domainType] - Domain type: 'ALLOWED_EMAIL_DOMAIN' or 'ORGANIZATION_DOMAIN'
+     *
+     * @returns {Promise<CreateDomainResponse>} The created domain with ID and verification status
+     *
+     * @throws {Error} If domain type is invalid
+     * @throws {Error} If domain is a blocked public domain (gmail.com, etc.)
+     *
+     * @example
+     * // Add SSO routing domain
+     * const response = await scalekitClient.domain.createDomain(
+     *   'org_123456',
+     *   'acme.com',
+     *   { domainType: 'ORGANIZATION_DOMAIN' }
+     * );
+     * console.log('Domain created:', response.domain.id);
+     * console.log('Verification required:', response.domain.verificationStatus);
+     *
+     * @example
+     * // Add allowed email domain for user suggestions
+     * await scalekitClient.domain.createDomain(
+     *   'org_123456',
+     *   'acme.io',
+     *   { domainType: 'ALLOWED_EMAIL_DOMAIN' }
+     * );
+     *
+     * @example
+     * // Create domain with default type
+     * await scalekitClient.domain.createDomain('org_123456', 'company.com');
+     *
+     * @example
+     * // Configure multiple domains for an organization
+     * const domains = ['acme.com', 'acme.io', 'acme.net'];
+     * for (const domain of domains) {
+     *   await scalekitClient.domain.createDomain('org_123456', domain, {
+     *     domainType: 'ORGANIZATION_DOMAIN'
+     *   });
+     * }
+     *
+     * @see {@link https://docs.scalekit.com/apis/#tag/domains | Create Domain API}
+     * @see {@link listDomains} - List all domains for an organization
+     * @see {@link deleteDomain} - Remove a domain
+     */
     createDomain(organizationId: string, name: string, options?: {
         domainType?: DomainType | string;
     }): Promise<CreateDomainResponse>;
     /**
-     * Get a specific domain by ID for an organization
-     * @param organizationId The organization id
-     * @param domainId The domain id
-     * @returns {Promise<GetDomainResponse>} The domain details
+     * Retrieves detailed information about a specific domain configuration.
+     *
+     * Returns complete domain details including the domain name, type (ORGANIZATION_DOMAIN or
+     * ALLOWED_EMAIL_DOMAIN), verification status, and when it was created/updated. Use this to
+     * check domain configuration status or verification requirements.
+     *
+     * @param {string} organizationId - The organization ID (format: "org_...")
+     * @param {string} domainId - The domain ID (format: "domain_...")
+     *
+     * @returns {Promise<GetDomainResponse>} Complete domain configuration and status
+     *
+     * @example
+     * // Check domain verification status
+     * const response = await scalekitClient.domain.getDomain(
+     *   'org_123456',
+     *   'domain_abc123'
+     * );
+     * console.log('Domain:', response.domain.domain);
+     * console.log('Type:', response.domain.domainType);
+     * console.log('Verified:', response.domain.verificationStatus);
+     *
+     * @example
+     * // Verify domain configuration after creation
+     * const created = await scalekitClient.domain.createDomain(
+     *   'org_123456',
+     *   'acme.com',
+     *   { domainType: 'ORGANIZATION_DOMAIN' }
+     * );
+     *
+     * // Later, check if domain has been verified
+     * const domain = await scalekitClient.domain.getDomain(
+     *   'org_123456',
+     *   created.domain.id
+     * );
+     * if (domain.domain.verificationStatus === 'VERIFIED') {
+     *   console.log('Domain is ready for SSO routing');
+     * }
+     *
+     * @see {@link https://docs.scalekit.com/apis/#tag/domains | Get Domain API}
+     * @see {@link createDomain} - Add a new domain
+     * @see {@link listDomains} - List all domains for an organization
      */
     getDomain(organizationId: string, domainId: string): Promise<GetDomainResponse>;
     /**
-     * List domains for an organization
-     * @param organizationId The organization id
-     * @returns {Promise<ListDomainResponse>} The list of domains for the organization
+     * Retrieves all domain configurations for an organization.
+     *
+     * Returns a complete list of domains configured for the organization, including both
+     * ORGANIZATION_DOMAIN (for SSO routing) and ALLOWED_EMAIL_DOMAIN (for user suggestions).
+     * Each domain includes its verification status, type, and configuration details.
+     *
+     * Use this to audit domain configuration, check which domains are verified, or display
+     * domain settings in an admin dashboard.
+     *
+     * @param {string} organizationId - The organization ID (format: "org_...")
+     *
+     * @returns {Promise<ListDomainResponse>} List of all domains with their configurations
+     *
+     * @example
+     * // List all domains for an organization
+     * const response = await scalekitClient.domain.listDomains('org_123456');
+     * console.log(`Found ${response.domains.length} domains`);
+     * response.domains.forEach(domain => {
+     *   console.log(`- ${domain.domain} (${domain.domainType}): ${domain.verificationStatus}`);
+     * });
+     *
+     * @example
+     * // Check which domains are verified for SSO
+     * const response = await scalekitClient.domain.listDomains('org_123456');
+     * const verifiedSSODomains = response.domains.filter(
+     *   d => d.domainType === 'ORGANIZATION_DOMAIN' && d.verificationStatus === 'VERIFIED'
+     * );
+     * console.log('Verified SSO domains:', verifiedSSODomains.map(d => d.domain));
+     * @see {@link https://docs.scalekit.com/apis/#tag/domains | List Domains API}
+     * @see {@link createDomain} - Add a new domain
+     * @see {@link getDomain} - Get details for a specific domain
+     * @see {@link deleteDomain} - Remove a domain
      */
     listDomains(organizationId: string): Promise<ListDomainResponse>;
+    /**
+     * Deletes a domain from an organization.
+     *
+     * Removes the domain configuration from the organization. Users with email addresses from
+     * this domain will no longer be automatically routed to this organization's SSO connection.
+     *
+     * @param {string} organizationId - The organization ID
+     * @param {string} domainId - The domain ID to delete
+     *
+     * @returns {Promise<Empty>} Empty response on successful deletion
+     *
+     * @example
+     * // Remove a domain from an organization
+     * await scalekitClient.domain.deleteDomain('org_123456', 'domain_abc123');
+     * console.log('Domain deleted successfully');
+     *
+     * @see {@link https://docs.scalekit.com/apis/#tag/domains | Delete Domain API}
+     * @see {@link createDomain} - Add a new domain
+     * @see {@link listDomains} - List all domains for an organization
+     */
     deleteDomain(organizationId: string, domainId: string): Promise<Empty>;
 }