Add session-management endpoints (#974)

## Description

Adds types/endpoints for session management.

## Documentation

Does this require changes to the WorkOS Docs? E.g. the [API
Reference](https://workos.com/docs/reference) or code snippets need
updates.

```
[X] Yes
```

If yes, link a related docs PR and add a docs maintainer as a reviewer.
Their approval is required.

Author: cmatheson

src/user-management/interfaces/authenticate-with-refresh-token-options.interface.ts

@@ -0,0 +1,19 @@
+import {
+  AuthenticateWithOptionsBase,
+  SerializedAuthenticateWithOptionsBase,
+} from './authenticate-with-options-base.interface';
+
+export interface AuthenticateWithRefreshTokenOptions
+  extends AuthenticateWithOptionsBase {
+  refreshToken: string;
+}
+
+export interface AuthenticateUserWithRefreshTokenCredentials {
+  clientSecret: string | undefined;
+}
+
+export interface SerializedAuthenticateWithRefreshTokenOptions
+  extends SerializedAuthenticateWithOptionsBase {
+  grant_type: 'refresh_token';
+  refresh_token: string;
+}

src/user-management/interfaces/authentication-response.interface.ts

@@ -3,9 +3,23 @@ import { User, UserResponse } from './user.interface';
 export interface AuthenticationResponse {
   user: User;
   organizationId?: string;
+  accessToken?: string;
+  refreshToken?: string;
 }
 
 export interface AuthenticationResponseResponse {
   user: UserResponse;
   organization_id?: string;
+  access_token?: string;
+  refresh_token?: string;
+}
+
+export interface RefreshAuthenticationResponse {
+  accessToken: string;
+  refreshToken: string;
+}
+
+export interface RefreshAuthenticationResponseResponse {
+  access_token: string;
+  refresh_token: string;
 }

src/user-management/interfaces/index.ts

@@ -1,6 +1,7 @@
 export * from './authenticate-with-magic-auth-options.interface';
 export * from './authenticate-with-password-options.interface';
 export * from './authenticate-with-code-options.interface';
+export * from './authenticate-with-refresh-token-options.interface';
 export * from './authenticate-with-totp-options.interface';
 export * from './authentication-response.interface';
 export * from './reset-password-options.interface';

src/user-management/interfaces/revoke-session-options.interface.ts

@@ -0,0 +1,13 @@
+export interface RevokeSessionOptions {
+  sessionId: string;
+}
+
+export interface SerializedRevokeSessionOptions {
+  session_id: string;
+}
+
+export const serializeRevokeSessionOptions = (
+  options: RevokeSessionOptions,
+): SerializedRevokeSessionOptions => ({
+  session_id: options.sessionId,
+});

src/user-management/serializers/authenticate-with-refresh-token.options.serializer.ts

@@ -0,0 +1,17 @@
+import {
+  AuthenticateUserWithCodeCredentials,
+  AuthenticateWithRefreshTokenOptions,
+  SerializedAuthenticateWithRefreshTokenOptions,
+} from '../interfaces';
+
+export const serializeAuthenticateWithRefreshTokenOptions = (
+  options: AuthenticateWithRefreshTokenOptions &
+    AuthenticateUserWithCodeCredentials,
+): SerializedAuthenticateWithRefreshTokenOptions => ({
+  grant_type: 'refresh_token',
+  client_id: options.clientId,
+  client_secret: options.clientSecret,
+  refresh_token: options.refreshToken,
+  ip_address: options.ipAddress,
+  user_agent: options.userAgent,
+});

src/user-management/serializers/authentication-response.serializer.ts

@@ -1,16 +1,34 @@
 import {
   AuthenticationResponse,
   AuthenticationResponseResponse,
+  RefreshAuthenticationResponse,
+  RefreshAuthenticationResponseResponse,
 } from '../interfaces';
 import { deserializeUser } from './user.serializer';
 
 export const deserializeAuthenticationResponse = (
   authenticationResponse: AuthenticationResponseResponse,
 ): AuthenticationResponse => {
-  const { user, organization_id, ...rest } = authenticationResponse;
+  const { user, organization_id, access_token, refresh_token, ...rest } =
+    authenticationResponse;
   return {
     user: deserializeUser(user),
     organizationId: organization_id,
+    accessToken: access_token,
+    refreshToken: refresh_token,
+    ...rest,
+  };
+};
+
+export const deserializeRefreshAuthenticationResponse = (
+  refreshAuthenticationResponse: RefreshAuthenticationResponseResponse,
+): RefreshAuthenticationResponse => {
+  const { access_token, refresh_token, ...rest } =
+    refreshAuthenticationResponse;
+
+  return {
+    accessToken: access_token,
+    refreshToken: refresh_token,
     ...rest,
   };
 };

src/user-management/serializers/index.ts

@@ -1,6 +1,7 @@
 export * from './authenticate-with-code-options.serializer';
 export * from './authenticate-with-magic-auth-options.serializer';
 export * from './authenticate-with-password-options.serializer';
+export * from './authenticate-with-refresh-token.options.serializer';
 export * from './authenticate-with-totp-options.serializer';
 export * from './authentication-response.serializer';
 export * from './enroll-auth-factor-options.serializer';

src/user-management/user-management.spec.ts

@@ -164,6 +164,32 @@ describe('UserManagement', () => {
     });
   });
 
+  describe('authenticateWithRefreshToken', () => {
+    it('sends a refresh_token authentication request', async () => {
+      fetchOnce({
+        access_token: 'access_token',
+        refresh_token: 'refreshToken2',
+      });
+      const resp = await workos.userManagement.authenticateWithRefreshToken({
+        clientId: 'proj_whatever',
+        refreshToken: 'refresh_token1',
+      });
+
+      expect(fetchURL()).toContain('/user_management/authenticate');
+      expect(fetchBody()).toEqual({
+        client_id: 'proj_whatever',
+        client_secret: 'sk_test_Sz3IQjepeSWaI4cMS4ms4sMuU',
+        refresh_token: 'refresh_token1',
+        grant_type: 'refresh_token',
+      });
+
+      expect(resp).toMatchObject({
+        accessToken: 'access_token',
+        refreshToken: 'refreshToken2',
+      });
+    });
+  });
+
   describe('authenticateUserWithTotp', () => {
     it('sends a token authentication request', async () => {
       fetchOnce({ user: userFixture });
@@ -710,6 +736,22 @@ describe('UserManagement', () => {
     });
   });
 
+  describe('revokeSession', () => {
+    it('sends a Revoke Session request', async () => {
+      const sessionId = 'session_12345';
+      fetchOnce({});
+
+      await workos.userManagement.revokeSession({
+        sessionId,
+      });
+
+      expect(fetchURL()).toContain('/user_management/sessions/revoke');
+      expect(fetchBody()).toEqual({
+        session_id: 'session_12345',
+      });
+    });
+  });
+
   describe('getAuthorizationUrl', () => {
     describe('with no custom api hostname', () => {
       it('generates an authorize url with the default api hostname', () => {
@@ -848,4 +890,18 @@ describe('UserManagement', () => {
       });
     });
   });
+
+  describe('getLogoutUrl', () => {
+    it('returns a logout url', () => {
+      const workos = new WorkOS('sk_test_Sz3IQjepeSWaI4cMS4ms4sMuU');
+
+      const url = workos.userManagement.getLogoutUrl({
+        sessionId: '123456',
+      });
+
+      expect(url).toBe(
+        'https://api.workos.com/user_management/sessions/logout?session_id=123456',
+      );
+    });
+  });
 });

src/user-management/user-management.ts

@@ -28,6 +28,10 @@ import {
   User,
   UserResponse,
   VerifyEmailOptions,
+  AuthenticateWithRefreshTokenOptions,
+  SerializedAuthenticateWithRefreshTokenOptions,
+  RefreshAuthenticationResponseResponse,
+  RefreshAuthenticationResponse,
 } from './interfaces';
 import {
   deserializeAuthenticationResponse,
@@ -43,6 +47,8 @@ import {
   serializeCreateUserOptions,
   serializeSendMagicAuthCodeOptions,
   serializeUpdateUserOptions,
+  deserializeRefreshAuthenticationResponse,
+  serializeAuthenticateWithRefreshTokenOptions,
 } from './serializers';
 import { fetchAndDeserialize } from '../common/utils/fetch-and-deserialize';
 import { Challenge, ChallengeResponse } from '../mfa/interfaces';
@@ -90,6 +96,11 @@ import {
   FactorWithSecretsResponse,
 } from './interfaces/factor.interface';
 import { deserializeFactor } from './serializers/factor.serializer';
+import {
+  RevokeSessionOptions,
+  SerializedRevokeSessionOptions,
+  serializeRevokeSessionOptions,
+} from './interfaces/revoke-session-options.interface';
 
 const toQueryString = (options: Record<string, string | undefined>): string => {
   const searchParams = new URLSearchParams();
@@ -196,6 +207,23 @@ export class UserManagement {
     return deserializeAuthenticationResponse(data);
   }
 
+  async authenticateWithRefreshToken(
+    payload: AuthenticateWithRefreshTokenOptions,
+  ): Promise<RefreshAuthenticationResponse> {
+    const { data } = await this.workos.post<
+      RefreshAuthenticationResponseResponse,
+      SerializedAuthenticateWithRefreshTokenOptions
+    >(
+      '/user_management/authenticate',
+      serializeAuthenticateWithRefreshTokenOptions({
+        ...payload,
+        clientSecret: this.workos.key,
+      }),
+    );
+
+    return deserializeRefreshAuthenticationResponse(data);
+  }
+
   async authenticateWithTotp(
     payload: AuthenticateWithTotpOptions,
   ): Promise<AuthenticationResponse> {
@@ -471,6 +499,13 @@ export class UserManagement {
     return deserializeInvitation(data);
   }
 
+  async revokeSession(payload: RevokeSessionOptions): Promise<void> {
+    await this.workos.post<void, SerializedRevokeSessionOptions>(
+      '/user_management/sessions/revoke',
+      serializeRevokeSessionOptions(payload),
+    );
+  }
+
   getAuthorizationUrl({
     connectionId,
     clientId,
@@ -482,7 +517,7 @@ export class UserManagement {
     state,
   }: AuthorizationURLOptions): string {
     if (!provider && !connectionId && !organizationId) {
-      throw new Error(
+      throw new TypeError(
         `Incomplete arguments. Need to specify either a 'connectionId', 'organizationId', or 'provider'.`,
       );
     }
@@ -501,4 +536,12 @@ export class UserManagement {
 
     return `${this.workos.baseURL}/user_management/authorize?${query}`;
   }
+
+  getLogoutUrl({ sessionId }: { sessionId: string }): string {
+    if (!sessionId) {
+      throw new TypeError(`Incomplete arguments. Need to specify 'sessionId'.`);
+    }
+
+    return `${this.workos.baseURL}/user_management/sessions/logout?session_id=${sessionId}`;
+  }
 }