feat(backend): add updateSession, mergeUser and the user.merged webhook (#10793)

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>

Author: dmoerner

.changeset/session-expiry-and-user-merge.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add `sessions.updateSession()` to change when a single session expires, and `users.mergeUser()` to merge one user into another. The `user.merged` webhook event is now part of `UserWebhookEvent`, with a payload typed as `UserMergedJSON`.

packages/backend/src/__tests__/user-merged-webhook.test.ts

@@ -0,0 +1,23 @@
+import { describe, expectTypeOf, test } from 'vitest';
+
+import type { UserJSON, UserWebhookEvent, WebhookEventType } from '../index';
+import type { verifyWebhook } from '../webhooks';
+
+type VerifiedEvent = Awaited<ReturnType<typeof verifyWebhook>>;
+
+describe('user.merged webhook', () => {
+  test('is a user webhook event type', () => {
+    expectTypeOf<'user.merged'>().toExtend<WebhookEventType>();
+    expectTypeOf<'user.merged'>().toExtend<UserWebhookEvent['type']>();
+  });
+
+  test('narrows to the remaining user and the deleted user', () => {
+    type Merged = Extract<VerifiedEvent, { type: 'user.merged' }>;
+    expectTypeOf<Merged['data']['user']>().toEqualTypeOf<UserJSON>();
+    expectTypeOf<Merged['data']['deleted_user']>().toEqualTypeOf<UserJSON>();
+  });
+
+  test('preserves the common resource ID used by existing webhook handlers', () => {
+    expectTypeOf<VerifiedEvent['data']['id']>().toEqualTypeOf<string | undefined>();
+  });
+});

packages/backend/src/api/__tests__/SessionApi.test.ts

@@ -16,6 +16,31 @@ describe('SessionAPI', () => {
     jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.test.token',
   };
 
+  describe('updateSession', () => {
+    it('calls PATCH /sessions/{id} with expire_at as an RFC 3339 timestamp', async () => {
+      const expireAt = new Date('2030-10-20T10:00:27.645Z');
+      server.use(
+        http.patch(
+          `https://api.clerk.test/v1/sessions/${sessionId}`,
+          validateHeaders(async ({ request }) => {
+            expect(await request.json()).toEqual({ expire_at: '2030-10-20T10:00:27.645Z' });
+            return HttpResponse.json({ object: 'session', id: sessionId, expire_at: expireAt.getTime() });
+          }),
+        ),
+      );
+
+      const response = await apiClient.sessions.updateSession(sessionId, { expireAt });
+      expect(response.id).toBe(sessionId);
+      expect(response.expireAt).toBe(expireAt.getTime());
+    });
+
+    it('requires a session ID', async () => {
+      await expect(apiClient.sessions.updateSession('', { expireAt: new Date() })).rejects.toThrow(
+        'A valid resource ID is required.',
+      );
+    });
+  });
+
   describe('getToken', () => {
     it('creates a session token without template', async () => {
       server.use(

packages/backend/src/api/__tests__/UserApi.test.ts

@@ -210,6 +210,34 @@ describe('UserAPI', () => {
     });
   });
 
+  describe('mergeUser', () => {
+    it('calls POST /users/{id}/merge and returns both users', async () => {
+      const postHandler = vi.fn(async ({ request }: { request: Request }) => {
+        expect(await request.json()).toEqual({ from_user_id: 'user_456', dry_run: true });
+        return HttpResponse.json({
+          user: { ...mockUserResponse, first_name: 'Remaining' },
+          deleted_user: { ...mockUserResponse, id: 'user_456', first_name: 'Deleted' },
+        });
+      });
+
+      server.use(http.post('https://api.clerk.test/v1/users/user_123/merge', validateHeaders(postHandler)));
+
+      const response = await apiClient.users.mergeUser('user_123', { fromUserId: 'user_456', dryRun: true });
+
+      expect(postHandler).toHaveBeenCalledTimes(1);
+      expect(response.user.id).toBe('user_123');
+      expect(response.user.firstName).toBe('Remaining');
+      expect(response.deletedUser.id).toBe('user_456');
+      expect(response.deletedUser.firstName).toBe('Deleted');
+    });
+
+    it('requires a user ID', async () => {
+      await expect(apiClient.users.mergeUser('', { fromUserId: 'user_456' })).rejects.toThrow(
+        'A valid resource ID is required.',
+      );
+    });
+  });
+
   describe('getUserOauthAccessToken', () => {
     it('exposes the provider error from a failed token retrieval', async () => {
       server.use(

packages/backend/src/api/endpoints/SessionApi.ts

@@ -43,6 +43,12 @@ export type CreateSessionParams = {
   userId: string;
 };
 
+/** @generateWithEmptyComment */
+export type UpdateSessionParams = {
+  /** When the session should expire. Must be at least 5 minutes and at most 10 years from now. */
+  expireAt: Date;
+};
+
 /** @generateWithEmptyComment */
 export class SessionAPI extends AbstractAPI {
   /**
@@ -81,6 +87,23 @@ export class SessionAPI extends AbstractAPI {
     });
   }
 
+  /**
+   * Changes when the given session expires. The new expiry applies to this session only and can exceed the instance's session lifetime. Only active and pending sessions can be updated.
+   *
+   * Take the session ID from the `sid` claim of a verified session token, never from an unverified client request.
+   * @param sessionId - The ID of the session to update.
+   * @param params - The parameters to update the session with.
+   * @returns The updated [`Session`](https://clerk.com/docs/reference/backend/types/backend-session).
+   */
+  public async updateSession(sessionId: string, params: UpdateSessionParams) {
+    this.requireId(sessionId);
+    return this.request<Session>({
+      method: 'PATCH',
+      path: joinPaths(basePath, sessionId),
+      bodyParams: params,
+    });
+  }
+
   /**
    * Revokes the given session. The user will be signed out from the client the session is associated with.
    * @param sessionId - The ID of the session to revoke.

packages/backend/src/api/endpoints/UserApi.ts

@@ -10,9 +10,10 @@ import type {
   OrganizationInvitation,
   OrganizationMembership,
   PhoneNumber,
-  User,
 } from '../resources';
 import type { PaginatedResourceResponse } from '../resources/Deserializer';
+import type { UserMergedJSON } from '../resources/JSON';
+import { User } from '../resources/User';
 import { AbstractAPI } from './AbstractApi';
 import type { WithSign } from './util-types';
 
@@ -425,6 +426,22 @@ export type SetPasswordCompromisedParams = {
   revokeAllSessions?: boolean;
 };
 
+/** @generateWithEmptyComment */
+export type MergeUserParams = {
+  /** The ID of the user to merge into the other user. This user is deleted. */
+  fromUserId: string;
+  /** Whether to return the result of the merge without changing anything. Defaults to `false`. */
+  dryRun?: boolean;
+};
+
+/** @generateWithEmptyComment */
+export type UserMergeResult = {
+  /** The user that remains, as it is after the merge. */
+  user: User;
+  /** The merged user as it was before it was deleted. */
+  deletedUser: User;
+};
+
 type ReplaceUserEmailAddressParams = {
   /** The new email address. Must adhere to the RFC 5322 specification for email address format. */
   emailAddress: string;
@@ -930,4 +947,22 @@ export class UserAPI extends AbstractAPI {
       path: joinPaths(basePath, userId, 'password', 'unset_compromised'),
     });
   }
+
+  /**
+   * Merges the `fromUserId` user into the given user: moves its identifications, connected accounts, second factors, organization memberships, and metadata onto the given user, then deletes the `fromUserId` user. Where both users have a value, the given user keeps its own.
+   *
+   * A merge cannot be undone. Use `dryRun` to preview one.
+   * @param userId - The ID of the user that remains after the merge.
+   * @param params - The parameters for the merge.
+   * @returns The remaining [`User`](https://clerk.com/docs/reference/backend/types/backend-user) after the merge, and the deleted user as it was before the merge.
+   */
+  public async mergeUser(userId: string, params: MergeUserParams): Promise<UserMergeResult> {
+    this.requireId(userId);
+    const result = await this.request<UserMergedJSON>({
+      method: 'POST',
+      path: joinPaths(basePath, userId, 'merge'),
+      bodyParams: params,
+    });
+    return { user: User.fromJSON(result.user), deletedUser: User.fromJSON(result.deleted_user) };
+  }
 }

packages/backend/src/api/resources/JSON.ts

@@ -763,6 +763,21 @@ export interface UserDeletedJSON extends DeletedObjectJSON {
   external_id?: string;
 }
 
+/**
+ * The result of merging one user into another.
+ * Used for `user.merged` webhook events and the response of the merge user endpoint.
+ */
+export interface UserMergedJSON {
+  /**
+   * The user that remains, as it is after the merge.
+   */
+  user: UserJSON;
+  /**
+   * The merged user as it was before it was deleted.
+   */
+  deleted_user: UserJSON;
+}
+
 /**
  * Directory group webhook event payload: a group as the identity provider reported it to a directory.
  * Used for `directoryGroup.created`, `directoryGroup.updated`, `directoryGroup.synced` and `directoryGroup.deleted` webhook events.

packages/backend/src/api/resources/Webhooks.ts

@@ -18,6 +18,7 @@ import type {
   SMSMessageJSON,
   UserDeletedJSON,
   UserJSON,
+  UserMergedJSON,
   WaitlistEntryJSON,
 } from './JSON';
 
@@ -37,9 +38,16 @@ type Webhook<EvtType, Data> = {
   instance_id: string;
 };
 
+/**
+ * `user.merged` carries two users instead of one resource, so its data has no `id` of its own.
+ * Declaring `id` as absent keeps `event.data.id` readable on a `WebhookEvent` that has not been narrowed by `type`.
+ */
+type UserMergedWebhookEventJSON = UserMergedJSON & { id?: never };
+
 export type UserWebhookEvent =
   | Webhook<'user.created' | 'user.updated', UserJSON>
-  | Webhook<'user.deleted', UserDeletedJSON>;
+  | Webhook<'user.deleted', UserDeletedJSON>
+  | Webhook<'user.merged', UserMergedWebhookEventJSON>;
 
 export type EmailWebhookEvent = Webhook<'email.created', EmailJSON>;
 

packages/backend/src/index.ts

@@ -103,6 +103,7 @@ export type {
   SMSMessageJSON,
   UserJSON,
   UserDeletedJSON,
+  UserMergedJSON,
   DirectoryGroupWebhookEventJSON,
   DirectoryGroupMembershipWebhookEventJSON,
   DeletedDirectoryGroupMembershipWebhookEventJSON,