feat: Introduce user latest session activity date and allow ordering & filtering when listing users

.changeset/funny-lamps-work.md

@@ -0,0 +1,7 @@
+---
+'@clerk/backend': minor
+---
+
+- Added the `User.last_active_at` timestamp field which stores the latest date of session activity, with day precision. For further details, please consult the [Backend API documentation](https://clerk.com/docs/reference/backend-api/tag/Users#operation/GetUser).
+- Added the `last_active_at_since` filtering parameter for the Users listing request. The new parameter can be used to retrieve users that have displayed session activity since the given date. For further details, please consult the [Backend API documentation](https://clerk.com/docs/reference/backend-api/tag/Users#operation/GetUserList).
+- Added the `last_active_at` available options for the `orderBy` parameter of the Users listing request. For further details, please consult the [Backend API documentation](https://clerk.com/docs/reference/backend-api/tag/Users#operation/GetUserList).

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

@@ -15,11 +15,22 @@ type UserCountParams = {
   query?: string;
   userId?: string[];
   externalId?: string[];
+  last_active_at_since?: number;
 };
 
 type UserListParams = ClerkPaginationRequest<
   UserCountParams & {
-    orderBy?: 'created_at' | 'updated_at' | '+created_at' | '+updated_at' | '-created_at' | '-updated_at';
+    orderBy?:
+      | 'created_at'
+      | 'updated_at'
+      | '+created_at'
+      | '+updated_at'
+      | '-created_at'
+      | '-updated_at'
+      | '+last_sign_in_at'
+      | '+last_active_at'
+      | '-last_sign_in_at'
+      | '-last_active_at';
   }
 >;
 

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

@@ -271,6 +271,7 @@ export interface UserJSON extends ClerkResourceJSON {
   unsafe_metadata: UserUnsafeMetadata;
   created_at: number;
   updated_at: number;
+  last_active_at: number | null;
 }
 
 export interface VerificationJSON extends ClerkResourceJSON {

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

@@ -33,6 +33,7 @@ export class User {
     readonly phoneNumbers: PhoneNumber[] = [],
     readonly web3Wallets: Web3Wallet[] = [],
     readonly externalAccounts: ExternalAccount[] = [],
+    readonly lastActiveAt: number | null,
   ) {}
 
   static fromJSON(data: UserJSON): User {
@@ -64,6 +65,7 @@ export class User {
       (data.phone_numbers || []).map(x => PhoneNumber.fromJSON(x)),
       (data.web3_wallets || []).map(x => Web3Wallet.fromJSON(x)),
       (data.external_accounts || []).map((x: ExternalAccountJSON) => ExternalAccount.fromJSON(x)),
+      data.last_active_at,
     );
   }
 }