@scalekit-sdk/node 2.1.6 → 2.1.8

package/buf.gen.yaml

@@ -19,3 +19,4 @@ types:
     - scalekit.v1.sessions
     - scalekit.v1.roles
     - scalekit.v1.auth
+    - scalekit.v1.auth.webauthn

package/lib/auth.d.ts

@@ -1,21 +1,53 @@
-import { Empty, PartialMessage, JsonValue } from '@bufbuild/protobuf';
-import CoreClient from './core';
-import GrpcConnect from './connect';
-import { User } from './pkg/grpc/scalekit/v1/auth/auth_pb';
+import { Empty, PartialMessage, JsonValue } from "@bufbuild/protobuf";
+import CoreClient from "./core";
+import GrpcConnect from "./connect";
+import { User } from "./pkg/grpc/scalekit/v1/auth/auth_pb";
 type UserInput = PartialMessage<User> & {
     customAttributes?: Record<string, JsonValue>;
 };
+/**
+ * If you are using Auth for MCP solution of Scalekit in "Bring your own Auth" mode, this client helps updating Scalekit with the currently logged in user details for the ongoing authentication request.
+ *
+ *
+ * @example
+ * const scalekitClient = new ScalekitClient(envUrl, clientId, clientSecret);
+ * const authClient = scalekitClient.auth;
+ *
+ * @see {@link https://docs.scalekit.com/apis/#tag/api%20auth | Authentication API Documentation}
+ */
 export default class AuthClient {
     private readonly grpcConnect;
     private readonly coreClient;
     private readonly client;
     constructor(grpcConnect: GrpcConnect, coreClient: CoreClient);
     /**
-     * Update user details for an ongoing login request.
-     * @param {string} connectionId The connection ID used for authentication.
-     * @param {string} loginRequestId The login request identifier issued during auth initiation.
-     * @param {UserInput} user User details to associate with the login request.
-     * @returns {Promise<Empty>} Empty response.
+     * Updates user details for an ongoing authentication request.
+     *
+     *
+     * @param {string} connectionId - The SSO connection ID being used for authentication
+     * @param {string} loginRequestId - The unique login request identifier from the auth flow
+     * @param {UserInput} user - User details to update or associate with the login request
+     * @param {string} [user.email] - User's email address
+     * @param {string} [user.sub] - Unique user identifier (subject)
+     *
+     * @returns {Promise<Empty>} Empty response on successful update
+     *
+     * @throws {Error} When connectionId is missing or invalid
+     * @throws {Error} When loginRequestId is missing or invalid
+     * @throws {Error} When user object is invalid
+     *
+     * @example
+     * await scalekitClient.auth.updateLoginUserDetails(
+     *   'conn_abc123',
+     *   'login_xyz789',
+     *   {
+     *     email: 'john.doe@company.com',
+     *     sub: 'unique_user_id_456',
+     *   }
+     * );
+     *
+     *
+     * @see {@link https://docs.scalekit.com/apis/#tag/api%20auth | Update Login User Details API}
      */
     updateLoginUserDetails(connectionId: string, loginRequestId: string, user: UserInput): Promise<Empty>;
 }

package/lib/auth.js

@@ -23,6 +23,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const protobuf_1 = require("@bufbuild/protobuf");
 const auth_connect_1 = require("./pkg/grpc/scalekit/v1/auth/auth_connect");
 const auth_pb_1 = require("./pkg/grpc/scalekit/v1/auth/auth_pb");
+/**
+ * If you are using Auth for MCP solution of Scalekit in "Bring your own Auth" mode, this client helps updating Scalekit with the currently logged in user details for the ongoing authentication request.
+ *
+ *
+ * @example
+ * const scalekitClient = new ScalekitClient(envUrl, clientId, clientSecret);
+ * const authClient = scalekitClient.auth;
+ *
+ * @see {@link https://docs.scalekit.com/apis/#tag/api%20auth | Authentication API Documentation}
+ */
 class AuthClient {
     constructor(grpcConnect, coreClient) {
         this.grpcConnect = grpcConnect;
@@ -30,22 +40,44 @@ class AuthClient {
         this.client = this.grpcConnect.createClient(auth_connect_1.AuthService);
     }
     /**
-     * Update user details for an ongoing login request.
-     * @param {string} connectionId The connection ID used for authentication.
-     * @param {string} loginRequestId The login request identifier issued during auth initiation.
-     * @param {UserInput} user User details to associate with the login request.
-     * @returns {Promise<Empty>} Empty response.
+     * Updates user details for an ongoing authentication request.
+     *
+     *
+     * @param {string} connectionId - The SSO connection ID being used for authentication
+     * @param {string} loginRequestId - The unique login request identifier from the auth flow
+     * @param {UserInput} user - User details to update or associate with the login request
+     * @param {string} [user.email] - User's email address
+     * @param {string} [user.sub] - Unique user identifier (subject)
+     *
+     * @returns {Promise<Empty>} Empty response on successful update
+     *
+     * @throws {Error} When connectionId is missing or invalid
+     * @throws {Error} When loginRequestId is missing or invalid
+     * @throws {Error} When user object is invalid
+     *
+     * @example
+     * await scalekitClient.auth.updateLoginUserDetails(
+     *   'conn_abc123',
+     *   'login_xyz789',
+     *   {
+     *     email: 'john.doe@company.com',
+     *     sub: 'unique_user_id_456',
+     *   }
+     * );
+     *
+     *
+     * @see {@link https://docs.scalekit.com/apis/#tag/api%20auth | Update Login User Details API}
      */
     updateLoginUserDetails(connectionId, loginRequestId, user) {
         return __awaiter(this, void 0, void 0, function* () {
-            if (!connectionId || typeof connectionId !== 'string') {
-                throw new Error('connectionId must be a non-empty string');
+            if (!connectionId || typeof connectionId !== "string") {
+                throw new Error("connectionId must be a non-empty string");
             }
-            if (!loginRequestId || typeof loginRequestId !== 'string') {
-                throw new Error('loginRequestId must be a non-empty string');
+            if (!loginRequestId || typeof loginRequestId !== "string") {
+                throw new Error("loginRequestId must be a non-empty string");
             }
-            if (!user || typeof user !== 'object') {
-                throw new Error('user must be a valid object');
+            if (!user || typeof user !== "object") {
+                throw new Error("user must be a valid object");
             }
             const { customAttributes } = user, rest = __rest(user, ["customAttributes"]);
             const userMessage = new auth_pb_1.User(rest);
@@ -55,7 +87,7 @@ class AuthClient {
             const request = new auth_pb_1.UpdateLoginUserDetailsRequest({
                 connectionId,
                 loginRequestId,
-                user: userMessage
+                user: userMessage,
             });
             return this.coreClient.connectExec(this.client.updateLoginUserDetails, request);
         });

package/lib/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAAA,iDAA8E;AAI9E,2EAAuE;AACvE,iEAA0F;AAM1F,MAAqB,UAAU;IAG7B,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,0BAAW,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;;OAMG;IACG,sBAAsB,CAC1B,YAAoB,EACpB,cAAsB,EACtB,IAAe;;YAEf,IAAI,CAAC,YAAY,IAAI,OAAO,YAAY,KAAK,QAAQ,EAAE,CAAC;gBACtD,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;YAC7D,CAAC;YAED,IAAI,CAAC,cAAc,IAAI,OAAO,cAAc,KAAK,QAAQ,EAAE,CAAC;gBAC1D,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;YAC/D,CAAC;YAED,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACtC,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;YACjD,CAAC;YAED,MAAM,EAAE,gBAAgB,KAAc,IAAI,EAAb,IAAI,UAAK,IAAI,EAApC,oBAA6B,CAAO,CAAC;YAC3C,MAAM,WAAW,GAAG,IAAI,cAAI,CAAC,IAA4B,CAAC,CAAC;YAE3D,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;gBACnC,WAAW,CAAC,gBAAgB,GAAG,iBAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;YACnE,CAAC;YAED,MAAM,OAAO,GAAG,IAAI,uCAA6B,CAAC;gBAChD,YAAY;gBACZ,cAAc;gBACd,IAAI,EAAE,WAAW;aAClB,CAAC,CAAC;YAEH,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAChC,IAAI,CAAC,MAAM,CAAC,sBAAsB,EAClC,OAAO,CACR,CAAC;QACJ,CAAC;KAAA;CACF;AApDD,6BAoDC"}
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAAA,iDAA8E;AAI9E,2EAAuE;AACvE,iEAG6C;AAM7C;;;;;;;;;GASG;AACH,MAAqB,UAAU;IAG7B,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,0BAAW,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,sBAAsB,CAC1B,YAAoB,EACpB,cAAsB,EACtB,IAAe;;YAEf,IAAI,CAAC,YAAY,IAAI,OAAO,YAAY,KAAK,QAAQ,EAAE,CAAC;gBACtD,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;YAC7D,CAAC;YAED,IAAI,CAAC,cAAc,IAAI,OAAO,cAAc,KAAK,QAAQ,EAAE,CAAC;gBAC1D,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;YAC/D,CAAC;YAED,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACtC,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;YACjD,CAAC;YAED,MAAM,EAAE,gBAAgB,KAAc,IAAI,EAAb,IAAI,UAAK,IAAI,EAApC,oBAA6B,CAAO,CAAC;YAC3C,MAAM,WAAW,GAAG,IAAI,cAAI,CAAC,IAA4B,CAAC,CAAC;YAE3D,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;gBACnC,WAAW,CAAC,gBAAgB,GAAG,iBAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;YACnE,CAAC;YAED,MAAM,OAAO,GAAG,IAAI,uCAA6B,CAAC;gBAChD,YAAY;gBACZ,cAAc;gBACd,IAAI,EAAE,WAAW;aAClB,CAAC,CAAC;YAEH,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAChC,IAAI,CAAC,MAAM,CAAC,sBAAsB,EAClC,OAAO,CACR,CAAC;QACJ,CAAC;KAAA;CACF;AA1ED,6BA0EC"}

package/lib/connection.d.ts

@@ -1,42 +1,216 @@
-import GrpcConnect from './connect';
-import CoreClient from './core';
-import { GetConnectionResponse, ToggleConnectionResponse, ListConnectionsResponse } from './pkg/grpc/scalekit/v1/connections/connections_pb';
+import GrpcConnect from "./connect";
+import CoreClient from "./core";
+import { GetConnectionResponse, ToggleConnectionResponse, ListConnectionsResponse } from "./pkg/grpc/scalekit/v1/connections/connections_pb";
+/**
+ * Client for managing enterprise SSO connections for organizations.
+ *
+ * Connections represent the SSO integration between an organization and their identity provider (IdP).
+ * Each organization can have an enterprise connection supporting different protocols (SAML, OIDC) and
+ * providers (Okta, Azure AD, Google Workspace, etc.). Use this client to retrieve connection details,
+ * list connections, and enable/disable them.
+ *
+ * @example
+ * const scalekitClient = new ScalekitClient(envUrl, clientId, clientSecret);
+ * const connectionClient = scalekitClient.connection;
+ *
+ * @see {@link https://docs.scalekit.com/apis/#tag/connections | Connection API Documentation}
+ */
 export default class ConnectionClient {
     private readonly grpcConncet;
     private readonly coreClient;
     private client;
     constructor(grpcConncet: GrpcConnect, coreClient: CoreClient);
     /**
-     * Get a connection by id and organization id
-     * @param organizationId The organization id
-     * @param id The connection id
-     * @returns {Promise<GetConnectionResponse>} The connection
+     * Retrieves complete configuration and status details for a specific SSO connection.
+     *
+     * Use this method to fetch comprehensive information about an organization's SSO connection,
+     * including provider settings, protocol details (SAML/OIDC), enabled status, and configuration
+     * metadata. This is useful for verifying connection setup, auditing configurations, checking
+     * connection health before authentication flows, or displaying connection details to administrators.
+     *
+     * @param {string} organizationId - The organization ID that owns the connection (format: "org_...")
+     * @param {string} id - The connection identifier to retrieve (format: "conn_...")
+     *
+     * @returns {Promise<GetConnectionResponse>} Response containing:
+     *   - connection: Complete connection object with:
+     *     - id: Unique connection identifier
+     *     - organizationId: Parent organization ID
+     *     - provider: Identity provider name (e.g., "okta", "azure_ad", "google")
+     *     - type: Protocol type ("saml", "oidc")
+     *     - enabled: Whether the connection is active
+     *     - status: Configuration status
+     *     - domains: Associated email domains for this connection
+     *     - metadata: Provider-specific configuration details
+     *     - createTime: When the connection was created
+     *     - updateTime: When the connection was last modified
+     *
+     * @throws {Error} If the organization or connection is not found
+     *
+     * @example
+     * // Get connection details
+     * const response = await scalekitClient.connection.getConnection(
+     *   'org_123456',
+     *   'conn_abc123'
+     * );
+     *
+     * const conn = response.connection;
+     * console.log('Provider:', conn.provider);
+     * console.log('Type:', conn.type);
+     * console.log('Status:', conn.enabled ? 'Enabled' : 'Disabled');
+     * console.log('Domains:', conn.domains);
+     *
+     * @example
+     * // Verify connection is ready for authentication
+     * const response = await scalekitClient.connection.getConnection(orgId, connId);
+     *
+     * if (response.connection.enabled && response.connection.status === 'active') {
+     *   console.log('Connection is ready for SSO authentication');
+     * } else {
+     *   console.log('Connection not ready:', response.connection.status);
+     * }
+     *
+     *
+     * @see {@link https://docs.scalekit.com/apis/#tag/connections | Get Connection API}
+     * @see {@link listConnections} - List all connections for an organization
+     * @see {@link enableConnection} - Enable this connection
+     * @see {@link disableConnection} - Disable this connection
      */
     getConnection(organizationId: string, id: string): Promise<GetConnectionResponse>;
     /**
-     * List connections by domain
-     * @param domain The domain
-     * @returns {Promise<ListConnectionsResponse>} The connection
+     * Lists all SSO connections associated with a specific email domain.
+     *
+     * Use this method to discover which organizations have SSO configured for a particular
+     * domain. This is useful for implementing domain-based SSO routing where users are
+     * automatically directed to their organization's SSO based on their email domain.
+     *
+     * @param {string} domain - The email domain to search for (e.g., "acme.com")
+     *
+     * @returns {Promise<ListConnectionsResponse>} Response containing:
+     *   - connections: Array of connection objects for the domain
+     *
+     * @example
+     * // Find SSO connections for a domain
+     * const response = await scalekitClient.connection.listConnectionsByDomain('acme.com');
+     *
+     * if (response.connections.length > 0) {
+     *   console.log('SSO available for domain acme.com');
+     *   const connection = response.connections[0];
+     *   console.log('Organization:', connection.organizationId);
+     *   console.log('Provider:', connection.provider);
+     * }
+     *
+     * @example
+     * // Implement domain-based SSO routing
+     * app.post('/auth/login', async (req, res) => {
+     *   const email = req.body.email;
+     *   const domain = email.split('@')[1];
+     *
+     *   const response = await scalekitClient.connection.listConnectionsByDomain(domain);
+     *
+     *   if (response.connections.length > 0) {
+     *     // Redirect to SSO
+     *     const authUrl = scalekitClient.getAuthorizationUrl(redirectUri, {
+     *       connectionId: response.connections[0].id,
+     *       loginHint: email
+     *     });
+     *     return res.redirect(authUrl);
+     *   } else {
+     *     // Use password-based login
+     *     return res.render('password-login');
+     *   }
+     * });
+     *
+     * @see {@link https://docs.scalekit.com/apis/#tag/connections | List Connections API}
+     * @see {@link listConnections} - List all connections for an organization
      */
     listConnectionsByDomain(domain: string): Promise<ListConnectionsResponse>;
     /**
-     * List connections by organization id
-     * @param organizationId The organization id
-     * @returns {Promise<ListConnectionsResponse>} The list of connections
+     * Lists all SSO connections configured for an organization.
+     *
+     * Retrieves all enterprise SSO connections (SAML, OIDC) that have been configured for
+     * the specified organization. Each connection includes details about the provider,
+     * status, and configuration.
+     *
+     * @param {string} organizationId - The organization ID
+     *
+     * @returns {Promise<ListConnectionsResponse>} Response containing:
+     *   - connections: Array of connection objects with provider details and status
+     *
+     * @example
+     * // List all SSO connections for an organization
+     * const response = await scalekitClient.connection.listConnections('org_123456');
+     *
+     * console.log(`Found ${response.connections.length} connections`);
+     * response.connections.forEach(conn => {
+     *   console.log(`- ${conn.provider} (${conn.type}): ${conn.enabled ? 'Enabled' : 'Disabled'}`);
+     * });
+     *
+     * @example
+     * // Check if organization has any enabled connections
+     * const response = await scalekitClient.connection.listConnections('org_123456');
+     * const hasEnabledSSO = response.connections.some(conn => conn.enabled);
+     *
+     * if (!hasEnabledSSO) {
+     *   console.log('No SSO connections enabled for this organization');
+     * }
+     *
+     * @see {@link https://docs.scalekit.com/apis/#tag/connections | List Connections API}
+     * @see {@link getConnection} - Get details of a specific connection
+     * @see {@link enableConnection} - Enable a connection
+     * @see {@link disableConnection} - Disable a connection
      */
     listConnections(organizationId: string): Promise<ListConnectionsResponse>;
     /**
-     * Enable a connection by id and organization id
-     * @param organizationId The organization id
-     * @param id The connection id
-     * @returns {Promise<ToggleConnectionResponse>} The connection enable response
+     * Enables an SSO connection for an organization.
+     *
+     * Activates a previously disabled or newly configured SSO connection, allowing users
+     * from the organization to authenticate using this identity provider. Once enabled,
+     * users can immediately start using SSO to log in.
+     *
+     * @param {string} organizationId - The organization ID
+     * @param {string} id - The connection ID to enable
+     *
+     * @returns {Promise<ToggleConnectionResponse>} Response with updated connection status
+     *
+     * @example
+     * // Enable an SSO connection
+     * const response = await scalekitClient.connection.enableConnection(
+     *   'org_123456',
+     *   'conn_abc123'
+     * );
+     *
+     * console.log('Connection enabled:', response.connection.enabled); // true
+     *
+     *
+     * @see {@link https://docs.scalekit.com/apis/#tag/connections | Enable Connection API}
+     * @see {@link disableConnection} - Disable a connection
+     * @see {@link listConnections} - List all connections
      */
     enableConnection(organizationId: string, id: string): Promise<ToggleConnectionResponse>;
     /**
-     * Disable a connection by id and organization id
-     * @param organizationId The organization id
-     * @param id The connection id
-     * @returns {Promise<ToggleConnectionResponse>} The connection enable response
+     * Disables an SSO connection for an organization.
+     *
+     * Deactivates an SSO connection, preventing users from authenticating via this identity
+     * provider. This is useful for temporarily suspending SSO access, during maintenance,
+     * or when migrating to a different provider. Existing user sessions remain valid.
+     *
+     * @param {string} organizationId - The organization ID
+     * @param {string} id - The connection ID to disable
+     *
+     * @returns {Promise<ToggleConnectionResponse>} Response with updated connection status
+     *
+     * @example
+     * // Disable an SSO connection
+     * const response = await scalekitClient.connection.disableConnection(
+     *   'org_123456',
+     *   'conn_abc123'
+     * );
+     *
+     * console.log('Connection disabled:', !response.connection.enabled); // true
+     *
+     * @see {@link https://docs.scalekit.com/apis/#tag/connections | Disable Connection API}
+     * @see {@link enableConnection} - Enable a connection
+     * @see {@link listConnections} - List all connections
      */
     disableConnection(organizationId: string, id: string): Promise<ToggleConnectionResponse>;
 }