@scalekit-sdk/node 2.1.7 → 2.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/buf.gen.yaml +1 -0
  2. package/lib/auth.d.ts +41 -9
  3. package/lib/auth.js +44 -12
  4. package/lib/auth.js.map +1 -1
  5. package/lib/connection.d.ts +195 -21
  6. package/lib/connection.js +197 -23
  7. package/lib/connection.js.map +1 -1
  8. package/lib/core.d.ts +2 -2
  9. package/lib/core.js +13 -12
  10. package/lib/core.js.map +1 -1
  11. package/lib/directory.d.ts +293 -40
  12. package/lib/directory.js +308 -44
  13. package/lib/directory.js.map +1 -1
  14. package/lib/domain.d.ts +166 -18
  15. package/lib/domain.js +178 -29
  16. package/lib/domain.js.map +1 -1
  17. package/lib/organization.d.ts +404 -44
  18. package/lib/organization.js +419 -54
  19. package/lib/organization.js.map +1 -1
  20. package/lib/permission.d.ts +179 -35
  21. package/lib/permission.js +190 -38
  22. package/lib/permission.js.map +1 -1
  23. package/lib/pkg/grpc/scalekit/v1/auth/auth_connect.d.ts +3 -3
  24. package/lib/pkg/grpc/scalekit/v1/auth/auth_connect.js +2 -2
  25. package/lib/pkg/grpc/scalekit/v1/auth/auth_connect.js.map +1 -1
  26. package/lib/pkg/grpc/scalekit/v1/auth/auth_pb.d.ts +16 -16
  27. package/lib/pkg/grpc/scalekit/v1/auth/auth_pb.js +21 -21
  28. package/lib/pkg/grpc/scalekit/v1/auth/auth_pb.js.map +1 -1
  29. package/lib/pkg/grpc/scalekit/v1/auth/webauthn_connect.d.ts +82 -0
  30. package/lib/pkg/grpc/scalekit/v1/auth/webauthn_connect.js +90 -0
  31. package/lib/pkg/grpc/scalekit/v1/auth/webauthn_connect.js.map +1 -0
  32. package/lib/pkg/grpc/scalekit/v1/auth/webauthn_pb.d.ts +647 -0
  33. package/lib/pkg/grpc/scalekit/v1/auth/webauthn_pb.js +993 -0
  34. package/lib/pkg/grpc/scalekit/v1/auth/webauthn_pb.js.map +1 -0
  35. package/lib/pkg/grpc/scalekit/v1/commons/commons_pb.d.ts +142 -0
  36. package/lib/pkg/grpc/scalekit/v1/commons/commons_pb.js +165 -1
  37. package/lib/pkg/grpc/scalekit/v1/commons/commons_pb.js.map +1 -1
  38. package/lib/pkg/grpc/scalekit/v1/connections/connections_connect.d.ts +1 -10
  39. package/lib/pkg/grpc/scalekit/v1/connections/connections_connect.js +0 -9
  40. package/lib/pkg/grpc/scalekit/v1/connections/connections_connect.js.map +1 -1
  41. package/lib/pkg/grpc/scalekit/v1/connections/connections_pb.d.ts +28 -63
  42. package/lib/pkg/grpc/scalekit/v1/connections/connections_pb.js +9 -90
  43. package/lib/pkg/grpc/scalekit/v1/connections/connections_pb.js.map +1 -1
  44. package/lib/pkg/grpc/scalekit/v1/users/users_pb.d.ts +2 -2
  45. package/lib/pkg/grpc/scalekit/v1/users/users_pb.js +1 -1
  46. package/lib/pkg/grpc/scalekit/v1/users/users_pb.js.map +1 -1
  47. package/lib/role.d.ts +252 -56
  48. package/lib/role.js +262 -62
  49. package/lib/role.js.map +1 -1
  50. package/lib/scalekit.d.ts +323 -54
  51. package/lib/scalekit.js +354 -76
  52. package/lib/scalekit.js.map +1 -1
  53. package/lib/session.d.ts +235 -22
  54. package/lib/session.js +237 -24
  55. package/lib/session.js.map +1 -1
  56. package/lib/user.d.ts +571 -53
  57. package/lib/user.js +598 -89
  58. package/lib/user.js.map +1 -1
  59. package/lib/webauthn.d.ts +33 -0
  60. package/lib/webauthn.js +80 -0
  61. package/lib/webauthn.js.map +1 -0
  62. package/package.json +2 -2
  63. package/src/auth.ts +53 -19
  64. package/src/connection.ts +237 -62
  65. package/src/core.ts +39 -33
  66. package/src/directory.ts +356 -98
  67. package/src/domain.ts +215 -68
  68. package/src/organization.ts +490 -112
  69. package/src/permission.ts +234 -88
  70. package/src/pkg/grpc/scalekit/v1/auth/auth_connect.ts +3 -3
  71. package/src/pkg/grpc/scalekit/v1/auth/auth_pb.ts +24 -24
  72. package/src/pkg/grpc/scalekit/v1/auth/webauthn_connect.ts +89 -0
  73. package/src/pkg/grpc/scalekit/v1/auth/webauthn_pb.ts +1263 -0
  74. package/src/pkg/grpc/scalekit/v1/commons/commons_pb.ts +217 -0
  75. package/src/pkg/grpc/scalekit/v1/connections/connections_connect.ts +1 -10
  76. package/src/pkg/grpc/scalekit/v1/connections/connections_pb.ts +42 -129
  77. package/src/pkg/grpc/scalekit/v1/users/users_pb.ts +3 -3
  78. package/src/role.ts +336 -136
  79. package/src/scalekit.ts +478 -149
  80. package/src/session.ts +266 -63
  81. package/src/user.ts +675 -168
  82. package/src/webauthn.ts +98 -0
package/lib/session.d.ts CHANGED
@@ -1,28 +1,112 @@
1
- import GrpcConnect from './connect';
2
- import CoreClient from './core';
3
- import { SessionDetails, UserSessionDetails, RevokeSessionResponse, RevokeAllUserSessionsResponse } from './pkg/grpc/scalekit/v1/sessions/sessions_pb';
1
+ import GrpcConnect from "./connect";
2
+ import CoreClient from "./core";
3
+ import { SessionDetails, UserSessionDetails, RevokeSessionResponse, RevokeAllUserSessionsResponse } from "./pkg/grpc/scalekit/v1/sessions/sessions_pb";
4
4
  export default class SessionClient {
5
5
  private readonly grpcConnect;
6
6
  private readonly coreClient;
7
7
  private client;
8
8
  constructor(grpcConnect: GrpcConnect, coreClient: CoreClient);
9
9
  /**
10
- * Get details for a specific session
11
- * @param {string} sessionId The session id
12
- * @returns {Promise<SessionDetails>} The session details
10
+ * Retrieves comprehensive metadata and status for a specific user session.
11
+ *
12
+ * Fetches complete session information including authentication status, device details,
13
+ * IP address, geolocation, and expiration timelines.
14
+ *
15
+ * @param {string} sessionId - The session identifier to retrieve (format: "ses_...")
16
+ *
17
+ * @returns {Promise<SessionDetails>} Session details containing:
18
+ * - sessionId: Unique session identifier
19
+ * - userId: User who owns this session
20
+ * - organizationId: Organization context for the session
21
+ * - status: Current session status ('active', 'expired', 'revoked', 'logout')
22
+ * - deviceInfo: Browser and operating system information
23
+ * - ipAddress: IP address from which session was created
24
+ * - geoLocation: Geographic location data (city, region, country)
25
+ * - createTime: When the session was created
26
+ * - lastActivityTime: Most recent session activity
27
+ * - idleExpirationTime: When session expires due to inactivity
28
+ * - absoluteExpirationTime: Maximum session lifetime
29
+ * - expirationTime: Actual expiration time (if session has ended)
30
+ *
31
+ * @throws {Error} If the session is not found
32
+ *
33
+ * @example
34
+ * // Get session details
35
+ * const session = await scalekitClient.session.getSession('ses_123456');
36
+ *
37
+ * console.log('Status:', session.status);
38
+ * console.log('User:', session.userId);
39
+ * console.log('Device:', session.deviceInfo);
40
+ * console.log('Location:', session.geoLocation);
41
+ * console.log('Last active:', session.lastActivityTime);
42
+ *
43
+ *
44
+ * @see {@link https://docs.scalekit.com/apis/#tag/sessions | Get Session API}
45
+ * @see {@link getUserSessions} - List all sessions for a user
46
+ * @see {@link revokeSession} - Revoke this session
13
47
  */
14
48
  getSession(sessionId: string): Promise<SessionDetails>;
15
49
  /**
16
- * Get all session details for a user with pagination and filtering
17
- * @param {string} userId The user id
18
- * @param {object} options The pagination and filtering options
19
- * @param {number} options.pageSize The page size
20
- * @param {string} options.pageToken The page token
21
- * @param {object} options.filter The session filter options
22
- * @param {string[]} options.filter.status The session statuses to filter by
23
- * @param {Date} options.filter.startTime The start time for filtering sessions
24
- * @param {Date} options.filter.endTime The end time for filtering sessions
25
- * @returns {Promise<UserSessionDetails>} The user session details
50
+ * Retrieves a paginated list of all sessions for a specific user across all devices and browsers.
51
+ *
52
+ * Lists all user sessions with support for filtering by status and time range. Essential for
53
+ * displaying active sessions in account management, auditing user activity, verifying authentication
54
+ * across devices, or identifying suspicious sessions. Use filtering to find active sessions,
55
+ * sessions from specific time periods, or sessions with particular statuses.
56
+ *
57
+ * @param {string} userId - The user identifier (format: "usr_...")
58
+ * @param {object} [options] - Optional pagination and filtering parameters
59
+ * @param {number} [options.pageSize] - Number of sessions to return per page
60
+ * @param {string} [options.pageToken] - Token for retrieving the next page from previous response
61
+ * @param {object} [options.filter] - Filter criteria for sessions
62
+ * @param {string[]} [options.filter.status] - Filter by status values: 'active', 'expired', 'revoked', 'logout'
63
+ * (multiple values use OR logic)
64
+ * @param {Date} [options.filter.startTime] - Include sessions created on or after this time
65
+ * @param {Date} [options.filter.endTime] - Include sessions created before this time
66
+ * (must be after startTime)
67
+ *
68
+ * @returns {Promise<UserSessionDetails>} Response containing:
69
+ * - sessions: Array of session objects with device info, location, and status
70
+ * - nextPageToken: Token for fetching the next page
71
+ * - totalSize: Total number of sessions matching the filter
72
+ *
73
+ * @example
74
+ * // List all active sessions for a user
75
+ * const response = await scalekitClient.session.getUserSessions('usr_123456', {
76
+ * filter: { status: ['active'] },
77
+ * pageSize: 20
78
+ * });
79
+ *
80
+ * console.log(`User has ${response.totalSize} active sessions`);
81
+ * response.sessions.forEach(session => {
82
+ * console.log(`- ${session.deviceInfo} from ${session.geoLocation?.city}`);
83
+ * console.log(` Last active: ${session.lastActivityTime}`);
84
+ * });
85
+ *
86
+ * @example
87
+ * // Get all sessions (active and inactive)
88
+ * const response = await scalekitClient.session.getUserSessions('usr_123456');
89
+ * console.log(`Total sessions: ${response.totalSize}`);
90
+ *
91
+ * @example
92
+ * // Find sessions from the last 7 days
93
+ * const sevenDaysAgo = new Date();
94
+ * sevenDaysAgo.setDate(sevenDaysAgo.getDate() - 7);
95
+ *
96
+ * const response = await scalekitClient.session.getUserSessions('usr_123456', {
97
+ * filter: {
98
+ * startTime: sevenDaysAgo,
99
+ * status: ['active', 'logout']
100
+ * }
101
+ * });
102
+ *
103
+ * console.log(`Sessions in last 7 days: ${response.sessions.length}`);
104
+ *
105
+ *
106
+ * @see {@link https://docs.scalekit.com/apis/#tag/sessions | List User Sessions API}
107
+ * @see {@link getSession} - Get details of a specific session
108
+ * @see {@link revokeSession} - Revoke a specific session
109
+ * @see {@link revokeAllUserSessions} - Revoke all sessions for user
26
110
  */
27
111
  getUserSessions(userId: string, options?: {
28
112
  pageSize?: number;
@@ -34,15 +118,144 @@ export default class SessionClient {
34
118
  };
35
119
  }): Promise<UserSessionDetails>;
36
120
  /**
37
- * Revoke a session for a user
38
- * @param {string} sessionId The session id to revoke
39
- * @returns {Promise<RevokeSessionResponse>} The response with revoked session details
121
+ * Immediately invalidates a specific user session by setting its status to 'revoked'.
122
+ *
123
+ * Terminates a single session, forcing the user to re-authenticate on that specific device.
124
+ * Use this for session-level logout, terminating suspicious sessions, forcing re-authentication
125
+ * on specific devices, or implementing "logout from this device" functionality. The revocation
126
+ * is instantaneous and irreversible - once revoked, the session cannot be used for any future
127
+ * API requests or application access.
128
+ *
129
+ * @param {string} sessionId - The session identifier to revoke (format: "ses_...")
130
+ *
131
+ * @returns {Promise<RevokeSessionResponse>} Response containing:
132
+ * - sessionId: The ID of the revoked session
133
+ * - userId: User who owned the session
134
+ * - revokedAt: Timestamp when the session was revoked
135
+ * - status: Updated session status ('revoked')
136
+ *
137
+ * @throws {Error} If the session is not found
138
+ *
139
+ * @example
140
+ * // Revoke a specific session
141
+ * const response = await scalekitClient.session.revokeSession('ses_123456');
142
+ * console.log('Session revoked at:', response.revokedAt);
143
+ * console.log('Status:', response.status); // 'revoked'
144
+ *
145
+ * @example
146
+ * // Logout from specific device
147
+ * app.post('/api/sessions/:sessionId/logout', async (req, res) => {
148
+ * const { sessionId } = req.params;
149
+ *
150
+ * try {
151
+ * await scalekitClient.session.revokeSession(sessionId);
152
+ * res.json({ message: 'Session terminated successfully' });
153
+ * } catch (error) {
154
+ * res.status(500).json({ error: 'Failed to revoke session' });
155
+ * }
156
+ * });
157
+ *
158
+ * @example
159
+ * // Revoke suspicious session
160
+ * const session = await scalekitClient.session.getSession(sessionId);
161
+ *
162
+ * if (session.geoLocation?.country !== expectedCountry) {
163
+ * console.log('Suspicious session detected');
164
+ * console.log(`Location: ${session.geoLocation?.city}, ${session.geoLocation?.country}`);
165
+ * console.log(`IP: ${session.ipAddress}`);
166
+ *
167
+ * await scalekitClient.session.revokeSession(sessionId);
168
+ * console.log('Session revoked for security');
169
+ *
170
+ * // Send security alert to user
171
+ * await sendSecurityAlert(session.userId, {
172
+ * message: 'Unusual login location detected and session terminated',
173
+ * location: session.geoLocation
174
+ * });
175
+ * }
176
+ *
177
+ * @example
178
+ * // Revoke all non-current sessions for a user
179
+ * const response = await scalekitClient.session.getUserSessions(userId, {
180
+ * filter: { status: ['active'] }
181
+ * });
182
+ *
183
+ * for (const session of response.sessions) {
184
+ * if (session.sessionId !== currentSessionId) {
185
+ * await scalekitClient.session.revokeSession(session.sessionId);
186
+ * console.log(`Revoked session from: ${session.deviceInfo}`);
187
+ * }
188
+ * }
189
+ *
190
+ * @see {@link https://docs.scalekit.com/apis/#tag/sessions | Revoke Session API}
191
+ * @see {@link revokeAllUserSessions} - Revoke all sessions for a user
192
+ * @see {@link getUserSessions} - List user sessions to find suspicious ones
193
+ * @see {@link getSession} - Get session details before revoking
40
194
  */
41
195
  revokeSession(sessionId: string): Promise<RevokeSessionResponse>;
42
196
  /**
43
- * Revoke all sessions for a user
44
- * @param {string} userId The user id whose sessions should be revoked
45
- * @returns {Promise<RevokeAllUserSessionsResponse>} The response with all revoked session details
197
+ * Immediately invalidates all active sessions for a user across all devices and browsers.
198
+ *
199
+ * Terminates all active sessions simultaneously, forcing the user to re-authenticate everywhere.
200
+ * Use this to implement global logout, force re-authentication after security incidents (password
201
+ * compromise, suspicious activity), terminate all sessions following password reset, or revoke
202
+ * access after account changes. Only active sessions are revoked; already expired, logout, or
203
+ * previously revoked sessions remain unchanged. This operation is atomic, instantaneous, and
204
+ * cannot be undone.
205
+ *
206
+ * @param {string} userId - The user identifier whose sessions should be revoked (format: "usr_...")
207
+ *
208
+ * @returns {Promise<RevokeAllUserSessionsResponse>} Response containing:
209
+ * - revokedSessions: Array of all revoked session objects with details
210
+ * - totalCount: Number of sessions that were revoked
211
+ * - revokedAt: Timestamp when revocation occurred
212
+ *
213
+ * @throws {Error} When userId is missing or invalid
214
+ * @throws {Error} If the user is not found
215
+ *
216
+ * @example
217
+ * // Revoke all user sessions (global logout)
218
+ * const response = await scalekitClient.session.revokeAllUserSessions('usr_123456');
219
+ *
220
+ * console.log(`Revoked ${response.totalCount} sessions`);
221
+ * console.log('User must re-authenticate on all devices');
222
+ *
223
+ * @example
224
+ * // Force logout after password reset
225
+ * app.post('/api/users/:userId/reset-password', async (req, res) => {
226
+ * const { userId } = req.params;
227
+ * const { newPassword } = req.body;
228
+ *
229
+ * try {
230
+ * // Update password
231
+ * await updateUserPassword(userId, newPassword);
232
+ *
233
+ * // Revoke all existing sessions
234
+ * const response = await scalekitClient.session.revokeAllUserSessions(userId);
235
+ *
236
+ * res.json({
237
+ * message: 'Password updated successfully',
238
+ * sessionsRevoked: response.totalCount,
239
+ * note: 'Please log in again with your new password'
240
+ * });
241
+ * } catch (error) {
242
+ * res.status(500).json({ error: 'Failed to reset password' });
243
+ * }
244
+ * });
245
+ *
246
+ * @example
247
+ * // Force re-authentication after role change
248
+ * async function updateUserRole(userId, newRole) {
249
+ * await updateRole(userId, newRole);
250
+ *
251
+ * // Force re-authentication to apply new permissions
252
+ * await scalekitClient.session.revokeAllUserSessions(userId);
253
+ * console.log('User will re-authenticate with new role permissions');
254
+ * }
255
+ *
256
+ * @see {@link https://docs.scalekit.com/apis/#tag/sessions | Revoke All Sessions API}
257
+ * @see {@link revokeSession} - Revoke a specific session
258
+ * @see {@link getUserSessions} - View user's active sessions before revoking
46
259
  */
47
260
  revokeAllUserSessions(userId: string): Promise<RevokeAllUserSessionsResponse>;
48
261
  }
package/lib/session.js CHANGED
@@ -19,33 +19,117 @@ class SessionClient {
19
19
  this.client = this.grpcConnect.createClient(sessions_connect_1.SessionService);
20
20
  }
21
21
  /**
22
- * Get details for a specific session
23
- * @param {string} sessionId The session id
24
- * @returns {Promise<SessionDetails>} The session details
22
+ * Retrieves comprehensive metadata and status for a specific user session.
23
+ *
24
+ * Fetches complete session information including authentication status, device details,
25
+ * IP address, geolocation, and expiration timelines.
26
+ *
27
+ * @param {string} sessionId - The session identifier to retrieve (format: "ses_...")
28
+ *
29
+ * @returns {Promise<SessionDetails>} Session details containing:
30
+ * - sessionId: Unique session identifier
31
+ * - userId: User who owns this session
32
+ * - organizationId: Organization context for the session
33
+ * - status: Current session status ('active', 'expired', 'revoked', 'logout')
34
+ * - deviceInfo: Browser and operating system information
35
+ * - ipAddress: IP address from which session was created
36
+ * - geoLocation: Geographic location data (city, region, country)
37
+ * - createTime: When the session was created
38
+ * - lastActivityTime: Most recent session activity
39
+ * - idleExpirationTime: When session expires due to inactivity
40
+ * - absoluteExpirationTime: Maximum session lifetime
41
+ * - expirationTime: Actual expiration time (if session has ended)
42
+ *
43
+ * @throws {Error} If the session is not found
44
+ *
45
+ * @example
46
+ * // Get session details
47
+ * const session = await scalekitClient.session.getSession('ses_123456');
48
+ *
49
+ * console.log('Status:', session.status);
50
+ * console.log('User:', session.userId);
51
+ * console.log('Device:', session.deviceInfo);
52
+ * console.log('Location:', session.geoLocation);
53
+ * console.log('Last active:', session.lastActivityTime);
54
+ *
55
+ *
56
+ * @see {@link https://docs.scalekit.com/apis/#tag/sessions | Get Session API}
57
+ * @see {@link getUserSessions} - List all sessions for a user
58
+ * @see {@link revokeSession} - Revoke this session
25
59
  */
26
60
  getSession(sessionId) {
27
61
  return __awaiter(this, void 0, void 0, function* () {
28
62
  return this.coreClient.connectExec(this.client.getSession, {
29
- sessionId
63
+ sessionId,
30
64
  });
31
65
  });
32
66
  }
33
67
  /**
34
- * Get all session details for a user with pagination and filtering
35
- * @param {string} userId The user id
36
- * @param {object} options The pagination and filtering options
37
- * @param {number} options.pageSize The page size
38
- * @param {string} options.pageToken The page token
39
- * @param {object} options.filter The session filter options
40
- * @param {string[]} options.filter.status The session statuses to filter by
41
- * @param {Date} options.filter.startTime The start time for filtering sessions
42
- * @param {Date} options.filter.endTime The end time for filtering sessions
43
- * @returns {Promise<UserSessionDetails>} The user session details
68
+ * Retrieves a paginated list of all sessions for a specific user across all devices and browsers.
69
+ *
70
+ * Lists all user sessions with support for filtering by status and time range. Essential for
71
+ * displaying active sessions in account management, auditing user activity, verifying authentication
72
+ * across devices, or identifying suspicious sessions. Use filtering to find active sessions,
73
+ * sessions from specific time periods, or sessions with particular statuses.
74
+ *
75
+ * @param {string} userId - The user identifier (format: "usr_...")
76
+ * @param {object} [options] - Optional pagination and filtering parameters
77
+ * @param {number} [options.pageSize] - Number of sessions to return per page
78
+ * @param {string} [options.pageToken] - Token for retrieving the next page from previous response
79
+ * @param {object} [options.filter] - Filter criteria for sessions
80
+ * @param {string[]} [options.filter.status] - Filter by status values: 'active', 'expired', 'revoked', 'logout'
81
+ * (multiple values use OR logic)
82
+ * @param {Date} [options.filter.startTime] - Include sessions created on or after this time
83
+ * @param {Date} [options.filter.endTime] - Include sessions created before this time
84
+ * (must be after startTime)
85
+ *
86
+ * @returns {Promise<UserSessionDetails>} Response containing:
87
+ * - sessions: Array of session objects with device info, location, and status
88
+ * - nextPageToken: Token for fetching the next page
89
+ * - totalSize: Total number of sessions matching the filter
90
+ *
91
+ * @example
92
+ * // List all active sessions for a user
93
+ * const response = await scalekitClient.session.getUserSessions('usr_123456', {
94
+ * filter: { status: ['active'] },
95
+ * pageSize: 20
96
+ * });
97
+ *
98
+ * console.log(`User has ${response.totalSize} active sessions`);
99
+ * response.sessions.forEach(session => {
100
+ * console.log(`- ${session.deviceInfo} from ${session.geoLocation?.city}`);
101
+ * console.log(` Last active: ${session.lastActivityTime}`);
102
+ * });
103
+ *
104
+ * @example
105
+ * // Get all sessions (active and inactive)
106
+ * const response = await scalekitClient.session.getUserSessions('usr_123456');
107
+ * console.log(`Total sessions: ${response.totalSize}`);
108
+ *
109
+ * @example
110
+ * // Find sessions from the last 7 days
111
+ * const sevenDaysAgo = new Date();
112
+ * sevenDaysAgo.setDate(sevenDaysAgo.getDate() - 7);
113
+ *
114
+ * const response = await scalekitClient.session.getUserSessions('usr_123456', {
115
+ * filter: {
116
+ * startTime: sevenDaysAgo,
117
+ * status: ['active', 'logout']
118
+ * }
119
+ * });
120
+ *
121
+ * console.log(`Sessions in last 7 days: ${response.sessions.length}`);
122
+ *
123
+ *
124
+ * @see {@link https://docs.scalekit.com/apis/#tag/sessions | List User Sessions API}
125
+ * @see {@link getSession} - Get details of a specific session
126
+ * @see {@link revokeSession} - Revoke a specific session
127
+ * @see {@link revokeAllUserSessions} - Revoke all sessions for user
44
128
  */
45
129
  getUserSessions(userId, options) {
46
130
  return __awaiter(this, void 0, void 0, function* () {
47
131
  const request = {
48
- userId
132
+ userId,
49
133
  };
50
134
  if ((options === null || options === void 0 ? void 0 : options.pageSize) !== undefined) {
51
135
  request.pageSize = options.pageSize;
@@ -70,29 +154,158 @@ class SessionClient {
70
154
  });
71
155
  }
72
156
  /**
73
- * Revoke a session for a user
74
- * @param {string} sessionId The session id to revoke
75
- * @returns {Promise<RevokeSessionResponse>} The response with revoked session details
157
+ * Immediately invalidates a specific user session by setting its status to 'revoked'.
158
+ *
159
+ * Terminates a single session, forcing the user to re-authenticate on that specific device.
160
+ * Use this for session-level logout, terminating suspicious sessions, forcing re-authentication
161
+ * on specific devices, or implementing "logout from this device" functionality. The revocation
162
+ * is instantaneous and irreversible - once revoked, the session cannot be used for any future
163
+ * API requests or application access.
164
+ *
165
+ * @param {string} sessionId - The session identifier to revoke (format: "ses_...")
166
+ *
167
+ * @returns {Promise<RevokeSessionResponse>} Response containing:
168
+ * - sessionId: The ID of the revoked session
169
+ * - userId: User who owned the session
170
+ * - revokedAt: Timestamp when the session was revoked
171
+ * - status: Updated session status ('revoked')
172
+ *
173
+ * @throws {Error} If the session is not found
174
+ *
175
+ * @example
176
+ * // Revoke a specific session
177
+ * const response = await scalekitClient.session.revokeSession('ses_123456');
178
+ * console.log('Session revoked at:', response.revokedAt);
179
+ * console.log('Status:', response.status); // 'revoked'
180
+ *
181
+ * @example
182
+ * // Logout from specific device
183
+ * app.post('/api/sessions/:sessionId/logout', async (req, res) => {
184
+ * const { sessionId } = req.params;
185
+ *
186
+ * try {
187
+ * await scalekitClient.session.revokeSession(sessionId);
188
+ * res.json({ message: 'Session terminated successfully' });
189
+ * } catch (error) {
190
+ * res.status(500).json({ error: 'Failed to revoke session' });
191
+ * }
192
+ * });
193
+ *
194
+ * @example
195
+ * // Revoke suspicious session
196
+ * const session = await scalekitClient.session.getSession(sessionId);
197
+ *
198
+ * if (session.geoLocation?.country !== expectedCountry) {
199
+ * console.log('Suspicious session detected');
200
+ * console.log(`Location: ${session.geoLocation?.city}, ${session.geoLocation?.country}`);
201
+ * console.log(`IP: ${session.ipAddress}`);
202
+ *
203
+ * await scalekitClient.session.revokeSession(sessionId);
204
+ * console.log('Session revoked for security');
205
+ *
206
+ * // Send security alert to user
207
+ * await sendSecurityAlert(session.userId, {
208
+ * message: 'Unusual login location detected and session terminated',
209
+ * location: session.geoLocation
210
+ * });
211
+ * }
212
+ *
213
+ * @example
214
+ * // Revoke all non-current sessions for a user
215
+ * const response = await scalekitClient.session.getUserSessions(userId, {
216
+ * filter: { status: ['active'] }
217
+ * });
218
+ *
219
+ * for (const session of response.sessions) {
220
+ * if (session.sessionId !== currentSessionId) {
221
+ * await scalekitClient.session.revokeSession(session.sessionId);
222
+ * console.log(`Revoked session from: ${session.deviceInfo}`);
223
+ * }
224
+ * }
225
+ *
226
+ * @see {@link https://docs.scalekit.com/apis/#tag/sessions | Revoke Session API}
227
+ * @see {@link revokeAllUserSessions} - Revoke all sessions for a user
228
+ * @see {@link getUserSessions} - List user sessions to find suspicious ones
229
+ * @see {@link getSession} - Get session details before revoking
76
230
  */
77
231
  revokeSession(sessionId) {
78
232
  return __awaiter(this, void 0, void 0, function* () {
79
233
  return this.coreClient.connectExec(this.client.revokeSession, {
80
- sessionId
234
+ sessionId,
81
235
  });
82
236
  });
83
237
  }
84
238
  /**
85
- * Revoke all sessions for a user
86
- * @param {string} userId The user id whose sessions should be revoked
87
- * @returns {Promise<RevokeAllUserSessionsResponse>} The response with all revoked session details
239
+ * Immediately invalidates all active sessions for a user across all devices and browsers.
240
+ *
241
+ * Terminates all active sessions simultaneously, forcing the user to re-authenticate everywhere.
242
+ * Use this to implement global logout, force re-authentication after security incidents (password
243
+ * compromise, suspicious activity), terminate all sessions following password reset, or revoke
244
+ * access after account changes. Only active sessions are revoked; already expired, logout, or
245
+ * previously revoked sessions remain unchanged. This operation is atomic, instantaneous, and
246
+ * cannot be undone.
247
+ *
248
+ * @param {string} userId - The user identifier whose sessions should be revoked (format: "usr_...")
249
+ *
250
+ * @returns {Promise<RevokeAllUserSessionsResponse>} Response containing:
251
+ * - revokedSessions: Array of all revoked session objects with details
252
+ * - totalCount: Number of sessions that were revoked
253
+ * - revokedAt: Timestamp when revocation occurred
254
+ *
255
+ * @throws {Error} When userId is missing or invalid
256
+ * @throws {Error} If the user is not found
257
+ *
258
+ * @example
259
+ * // Revoke all user sessions (global logout)
260
+ * const response = await scalekitClient.session.revokeAllUserSessions('usr_123456');
261
+ *
262
+ * console.log(`Revoked ${response.totalCount} sessions`);
263
+ * console.log('User must re-authenticate on all devices');
264
+ *
265
+ * @example
266
+ * // Force logout after password reset
267
+ * app.post('/api/users/:userId/reset-password', async (req, res) => {
268
+ * const { userId } = req.params;
269
+ * const { newPassword } = req.body;
270
+ *
271
+ * try {
272
+ * // Update password
273
+ * await updateUserPassword(userId, newPassword);
274
+ *
275
+ * // Revoke all existing sessions
276
+ * const response = await scalekitClient.session.revokeAllUserSessions(userId);
277
+ *
278
+ * res.json({
279
+ * message: 'Password updated successfully',
280
+ * sessionsRevoked: response.totalCount,
281
+ * note: 'Please log in again with your new password'
282
+ * });
283
+ * } catch (error) {
284
+ * res.status(500).json({ error: 'Failed to reset password' });
285
+ * }
286
+ * });
287
+ *
288
+ * @example
289
+ * // Force re-authentication after role change
290
+ * async function updateUserRole(userId, newRole) {
291
+ * await updateRole(userId, newRole);
292
+ *
293
+ * // Force re-authentication to apply new permissions
294
+ * await scalekitClient.session.revokeAllUserSessions(userId);
295
+ * console.log('User will re-authenticate with new role permissions');
296
+ * }
297
+ *
298
+ * @see {@link https://docs.scalekit.com/apis/#tag/sessions | Revoke All Sessions API}
299
+ * @see {@link revokeSession} - Revoke a specific session
300
+ * @see {@link getUserSessions} - View user's active sessions before revoking
88
301
  */
89
302
  revokeAllUserSessions(userId) {
90
303
  return __awaiter(this, void 0, void 0, function* () {
91
304
  if (!userId) {
92
- throw new Error('userId is required');
305
+ throw new Error("userId is required");
93
306
  }
94
307
  return this.coreClient.connectExec(this.client.revokeAllUserSessions, {
95
- userId
308
+ userId,
96
309
  });
97
310
  });
98
311
  }
@@ -1 +1 @@
1
- {"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":";;;;;;;;;;;AAIA,uFAAkF;AAClF,6EAUqD;AACrD,iDAA+C;AAE/C,MAAqB,aAAa;IAGhC,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,iCAAc,CAAC,CAAC;IAC9D,CAAC;IAED;;;;OAIG;IACG,UAAU,CAAC,SAAiB;;YAChC,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAChC,IAAI,CAAC,MAAM,CAAC,UAAU,EACtB;gBACE,SAAS;aACV,CACF,CAAC;QACJ,CAAC;KAAA;IAED;;;;;;;;;;;OAWG;IACG,eAAe,CACnB,MAAc,EACd,OAQC;;YAED,MAAM,OAAO,GAA8C;gBACzD,MAAM;aACP,CAAC;YAEF,IAAI,CAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,QAAQ,MAAK,SAAS,EAAE,CAAC;gBACpC,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;YACtC,CAAC;YAED,IAAI,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,SAAS,EAAE,CAAC;gBACvB,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;YACxC,CAAC;YAED,IAAI,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,EAAE,CAAC;gBACpB,MAAM,MAAM,GAAG,IAAI,+BAAiB,EAAE,CAAC;gBAEvC,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;oBAC1B,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC;gBACxC,CAAC;gBAED,IAAI,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;oBAC7B,MAAM,CAAC,SAAS,GAAG,oBAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;gBAClE,CAAC;gBAED,IAAI,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;oBAC3B,MAAM,CAAC,OAAO,GAAG,oBAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBAC9D,CAAC;gBAED,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC;YAC1B,CAAC;YAED,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAChC,IAAI,CAAC,MAAM,CAAC,eAAe,EAC3B,OAAO,CACR,CAAC;QACJ,CAAC;KAAA;IAED;;;;OAIG;IACG,aAAa,CAAC,SAAiB;;YACnC,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAChC,IAAI,CAAC,MAAM,CAAC,aAAa,EACzB;gBACE,SAAS;aACV,CACF,CAAC;QACJ,CAAC;KAAA;IAED;;;;OAIG;IACG,qBAAqB,CAAC,MAAc;;YACxC,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;YACxC,CAAC;YAED,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAChC,IAAI,CAAC,MAAM,CAAC,qBAAqB,EACjC;gBACE,MAAM;aACP,CACF,CAAC;QACJ,CAAC;KAAA;CACF;AAnHD,gCAmHC"}
1
+ {"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":";;;;;;;;;;;AAIA,uFAAkF;AAClF,6EAUqD;AACrD,iDAA+C;AAE/C,MAAqB,aAAa;IAGhC,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,iCAAc,CAAC,CAAC;IAC9D,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACG,UAAU,CAAC,SAAiB;;YAChC,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE;gBACzD,SAAS;aACV,CAAC,CAAC;QACL,CAAC;KAAA;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6DG;IACG,eAAe,CACnB,MAAc,EACd,OAQC;;YAED,MAAM,OAAO,GAA8C;gBACzD,MAAM;aACP,CAAC;YAEF,IAAI,CAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,QAAQ,MAAK,SAAS,EAAE,CAAC;gBACpC,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;YACtC,CAAC;YAED,IAAI,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,SAAS,EAAE,CAAC;gBACvB,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;YACxC,CAAC;YAED,IAAI,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,EAAE,CAAC;gBACpB,MAAM,MAAM,GAAG,IAAI,+BAAiB,EAAE,CAAC;gBAEvC,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;oBAC1B,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC;gBACxC,CAAC;gBAED,IAAI,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;oBAC7B,MAAM,CAAC,SAAS,GAAG,oBAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;gBAClE,CAAC;gBAED,IAAI,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;oBAC3B,MAAM,CAAC,OAAO,GAAG,oBAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBAC9D,CAAC;gBAED,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC;YAC1B,CAAC;YAED,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QAC3E,CAAC;KAAA;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0EG;IACG,aAAa,CAAC,SAAiB;;YACnC,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE;gBAC5D,SAAS;aACV,CAAC,CAAC;QACL,CAAC;KAAA;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+DG;IACG,qBAAqB,CACzB,MAAc;;YAEd,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;YACxC,CAAC;YAED,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,qBAAqB,EAAE;gBACpE,MAAM;aACP,CAAC,CAAC;QACL,CAAC;KAAA;CACF;AA9TD,gCA8TC"}