@scalekit-sdk/node 2.1.7 → 2.1.8

package/lib/domain.js

@@ -11,6 +11,19 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 const domains_connect_1 = require("./pkg/grpc/scalekit/v1/domains/domains_connect");
 const domains_pb_1 = require("./pkg/grpc/scalekit/v1/domains/domains_pb");
+/**
+ * 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}
+ */
 class DomainClient {
     constructor(grpcConncet, coreClient) {
         this.grpcConncet = grpcConncet;
@@ -18,21 +31,71 @@ class DomainClient {
         this.client = this.grpcConncet.createClient(domains_connect_1.DomainService);
     }
     /**
-     * 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, name, options) {
         return __awaiter(this, void 0, void 0, function* () {
             let domainTypeValue;
             if (options === null || options === void 0 ? void 0 : options.domainType) {
-                if (typeof options.domainType === 'string') {
-                    domainTypeValue = domains_pb_1.DomainType[options.domainType];
+                if (typeof options.domainType === "string") {
+                    domainTypeValue =
+                        domains_pb_1.DomainType[options.domainType];
                     if (domainTypeValue === undefined) {
-                        throw new Error('Invalid domain type');
+                        throw new Error("Invalid domain type");
                     }
                 }
                 else {
@@ -41,53 +104,139 @@ class DomainClient {
             }
             return this.coreClient.connectExec(this.client.createDomain, {
                 identities: {
-                    case: 'organizationId',
-                    value: organizationId
+                    case: "organizationId",
+                    value: organizationId,
                 },
-                domain: Object.assign({ domain: name }, (domainTypeValue && { domainType: domainTypeValue }))
+                domain: Object.assign({ domain: name }, (domainTypeValue && { domainType: domainTypeValue })),
             });
         });
     }
     /**
-     * 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, domainId) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.coreClient.connectExec(this.client.getDomain, {
                 id: domainId,
                 identities: {
-                    case: 'organizationId',
-                    value: organizationId
-                }
+                    case: "organizationId",
+                    value: organizationId,
+                },
             });
         });
     }
     /**
-     * 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) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.coreClient.connectExec(this.client.listDomains, {
                 identities: {
-                    case: 'organizationId',
-                    value: organizationId
-                }
+                    case: "organizationId",
+                    value: organizationId,
+                },
             });
         });
     }
+    /**
+     * 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, domainId) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.coreClient.connectExec(this.client.deleteDomain, {
                 id: domainId,
                 identities: {
-                    case: 'organizationId',
-                    value: organizationId
-                }
+                    case: "organizationId",
+                    value: organizationId,
+                },
             });
         });
     }

package/lib/domain.js.map

@@ -1 +1 @@
-{"version":3,"file":"domain.js","sourceRoot":"","sources":["../src/domain.ts"],"names":[],"mappings":";;;;;;;;;;;AAGA,oFAA+E;AAC/E,0EAAoI;AAGpI,MAAqB,YAAY;IAE/B,YACmB,WAAwB,EACxB,UAAsB;QADtB,gBAAW,GAAX,WAAW,CAAa;QACxB,eAAU,GAAV,UAAU,CAAY;QAEvC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,YAAY,CAAC,+BAAa,CAAC,CAAC;IAC7D,CAAC;IAED;;;;;;;MAOE;IACI,YAAY,CAAC,cAAsB,EAAE,IAAY,EAAE,OAA8C;;YACrG,IAAI,eAAuC,CAAC;YAC5C,IAAI,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,UAAU,EAAE,CAAC;gBACxB,IAAI,OAAO,OAAO,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;oBAC3C,eAAe,GAAG,uBAAU,CAAC,OAAO,CAAC,UAAqC,CAAC,CAAC;oBAC5E,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;wBAClC,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;oBACzC,CAAC;gBACH,CAAC;qBAAM,CAAC;oBACN,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;gBACvC,CAAC;YACH,CAAC;YAED,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAChC,IAAI,CAAC,MAAM,CAAC,YAAY,EACxB;gBACE,UAAU,EAAE;oBACV,IAAI,EAAE,gBAAgB;oBACtB,KAAK,EAAE,cAAc;iBACtB;gBACD,MAAM,kBACJ,MAAM,EAAE,IAAI,IACT,CAAC,eAAe,IAAI,EAAE,UAAU,EAAE,eAAe,EAAE,CAAC,CACxD;aACF,CACF,CAAA;QACH,CAAC;KAAA;IAED;;;;;OAKG;IACG,SAAS,CAAC,cAAsB,EAAE,QAAgB;;YACtD,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAChC,IAAI,CAAC,MAAM,CAAC,SAAS,EACrB;gBACE,EAAE,EAAE,QAAQ;gBACZ,UAAU,EAAE;oBACV,IAAI,EAAE,gBAAgB;oBACtB,KAAK,EAAE,cAAc;iBACtB;aACF,CACF,CAAC;QACJ,CAAC;KAAA;IAED;;;;OAIG;IACG,WAAW,CAAC,cAAsB;;YACtC,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAChC,IAAI,CAAC,MAAM,CAAC,WAAW,EACvB;gBACE,UAAU,EAAE;oBACV,IAAI,EAAE,gBAAgB;oBACtB,KAAK,EAAE,cAAc;iBACtB;aACF,CACF,CAAC;QACJ,CAAC;KAAA;IAEK,YAAY,CAAC,cAAsB,EAAE,QAAgB;;YACzD,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAChC,IAAI,CAAC,MAAM,CAAC,YAAY,EACxB;gBACE,EAAE,EAAE,QAAQ;gBACZ,UAAU,EAAE;oBACV,IAAI,EAAE,gBAAgB;oBACtB,KAAK,EAAE,cAAc;iBACtB;aACF,CACF,CAAC;QACJ,CAAC;KAAA;CAEF;AA9FD,+BA8FC"}
+{"version":3,"file":"domain.js","sourceRoot":"","sources":["../src/domain.ts"],"names":[],"mappings":";;;;;;;;;;;AAGA,oFAA+E;AAC/E,0EAKmD;AAGnD;;;;;;;;;;;;GAYG;AACH,MAAqB,YAAY;IAE/B,YACmB,WAAwB,EACxB,UAAsB;QADtB,gBAAW,GAAX,WAAW,CAAa;QACxB,eAAU,GAAV,UAAU,CAAY;QAEvC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,YAAY,CAAC,+BAAa,CAAC,CAAC;IAC7D,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwDG;IACG,YAAY,CAChB,cAAsB,EACtB,IAAY,EACZ,OAA8C;;YAE9C,IAAI,eAAuC,CAAC;YAC5C,IAAI,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,UAAU,EAAE,CAAC;gBACxB,IAAI,OAAO,OAAO,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;oBAC3C,eAAe;wBACb,uBAAU,CAAC,OAAO,CAAC,UAAqC,CAAC,CAAC;oBAC5D,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;wBAClC,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;oBACzC,CAAC;gBACH,CAAC;qBAAM,CAAC;oBACN,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;gBACvC,CAAC;YACH,CAAC;YAED,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE;gBAC3D,UAAU,EAAE;oBACV,IAAI,EAAE,gBAAgB;oBACtB,KAAK,EAAE,cAAc;iBACtB;gBACD,MAAM,kBACJ,MAAM,EAAE,IAAI,IACT,CAAC,eAAe,IAAI,EAAE,UAAU,EAAE,eAAe,EAAE,CAAC,CACxD;aACF,CAAC,CAAC;QACL,CAAC;KAAA;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACG,SAAS,CACb,cAAsB,EACtB,QAAgB;;YAEhB,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE;gBACxD,EAAE,EAAE,QAAQ;gBACZ,UAAU,EAAE;oBACV,IAAI,EAAE,gBAAgB;oBACtB,KAAK,EAAE,cAAc;iBACtB;aACF,CAAC,CAAC;QACL,CAAC;KAAA;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,WAAW,CAAC,cAAsB;;YACtC,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE;gBAC1D,UAAU,EAAE;oBACV,IAAI,EAAE,gBAAgB;oBACtB,KAAK,EAAE,cAAc;iBACtB;aACF,CAAC,CAAC;QACL,CAAC;KAAA;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACG,YAAY,CAAC,cAAsB,EAAE,QAAgB;;YACzD,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE;gBAC3D,EAAE,EAAE,QAAQ;gBACZ,UAAU,EAAE;oBACV,IAAI,EAAE,gBAAgB;oBACtB,KAAK,EAAE,cAAc;iBACtB;aACF,CAAC,CAAC;QACL,CAAC;KAAA;CACF;AAhOD,+BAgOC"}