feat(backend): Add last_active_at field & last_active_at_since parame…

…ter (#2261)

- User.last_active_at stores the last date of session activity for the user,
  with day precision
- last_active_at can be used to order users when listing
- last_active_at_since can be used to filter users based on their latest
  activity date

.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,
     );
   }
 }