feat(backend): Add waitlist entries to Backend API client

Author: tmilewski

.changeset/thick-showers-drop.md

@@ -0,0 +1,18 @@
+---
+'@clerk/backend': patch
+---
+
+Adds the ability to list and create waitlist entries to the Backend API client.
+
+
+```ts
+  import { createClerkClient } from '@clerk/backend';
+
+  const clerkClient = createClerkClient(...);
+
+  await clerkClient.waitlistEntries.list({...});
+  await clerkClient.waitlistEntries.create({
+    emailAddress: '[email protected]', 
+    notify: true
+  });
+```

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

@@ -0,0 +1,41 @@
+import type { ClerkPaginationRequest } from '@clerk/types';
+
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
+import type { WaitlistEntryStatus } from '../resources/Enums';
+import type { WaitlistEntry } from '../resources/WaitlistEntry';
+import { AbstractAPI } from './AbstractApi';
+import type { WithSign } from './util-types';
+
+const basePath = '/waitlist_entries';
+
+type WaitlistEntryListParams = ClerkPaginationRequest<{
+  /**
+   * Filter waitlist entries by `email_address` or `id`
+   */
+  query?: string;
+  status?: WaitlistEntryStatus;
+  orderBy?: WithSign<'created_at' | 'invited_at' | 'email_address'>;
+}>;
+
+type WaitlistEntryCreateParams = {
+  emailAddress: string;
+  notify?: boolean;
+};
+
+export class WaitlistEntryAPI extends AbstractAPI {
+  public async list(params: WaitlistEntryListParams = {}) {
+    return this.request<PaginatedResourceResponse<WaitlistEntry>>({
+      method: 'GET',
+      path: basePath,
+      queryParams: params,
+    });
+  }
+
+  public async create(params: WaitlistEntryCreateParams) {
+    return this.request<WaitlistEntry>({
+      method: 'POST',
+      path: basePath,
+      bodyParams: params,
+    });
+  }
+}

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

@@ -13,3 +13,4 @@ export * from './SignInTokenApi';
 export * from './UserApi';
 export * from './SamlConnectionApi';
 export * from './TestingTokenApi';
+export * from './WaitlistEntryApi';

packages/backend/src/api/factory.ts

@@ -13,6 +13,7 @@ import {
   SignInTokenAPI,
   TestingTokenAPI,
   UserAPI,
+  WaitlistEntryAPI,
 } from './endpoints';
 import { buildRequest } from './request';
 
@@ -40,5 +41,6 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
     domains: new DomainAPI(request),
     samlConnections: new SamlConnectionAPI(request),
     testingTokens: new TestingTokenAPI(request),
+    waitlistEntries: new WaitlistEntryAPI(request),
   };
 }

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

@@ -21,6 +21,7 @@ import {
 import { AccountlessApplication } from './AccountlessApplication';
 import type { PaginatedResponseJSON } from './JSON';
 import { ObjectType } from './JSON';
+import { WaitlistEntry } from './WaitlistEntry';
 
 type ResourceResponse<T> = {
   data: T;
@@ -105,6 +106,8 @@ function jsonToObject(item: any): any {
       return getCount(item);
     case ObjectType.User:
       return User.fromJSON(item);
+    case ObjectType.WaitlistEntry:
+      return WaitlistEntry.fromJSON(item);
     default:
       return item;
   }

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

@@ -36,3 +36,5 @@ export type SignInStatus = 'needs_identifier' | 'needs_factor_one' | 'needs_fact
 export type SignUpStatus = 'missing_requirements' | 'complete' | 'abandoned';
 
 export type InvitationStatus = 'pending' | 'accepted' | 'revoked' | 'expired';
+
+export type WaitlistEntryStatus = 'pending' | 'invited' | 'completed' | 'rejected';

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

@@ -7,6 +7,7 @@ import type {
   OrganizationMembershipRole,
   SignInStatus,
   SignUpStatus,
+  WaitlistEntryStatus,
 } from './Enums';
 
 export const ObjectType = {
@@ -385,13 +386,13 @@ export interface VerificationJSON extends ClerkResourceJSON {
 }
 
 export interface WaitlistEntryJSON extends ClerkResourceJSON {
-  created_at: number;
-  email_address: string;
+  object: typeof ObjectType.WaitlistEntry;
   id: string;
+  status: WaitlistEntryStatus;
+  email_address: string;
   invitation: InvitationJSON | null;
   is_locked: boolean;
-  object: typeof ObjectType.WaitlistEntry;
-  status: string;
+  created_at: number;
   updated_at: number;
 }
 
@@ -482,3 +483,29 @@ export interface SamlAccountConnectionJSON extends ClerkResourceJSON {
   created_at: number;
   updated_at: number;
 }
+
+// export type WaitlistEntry = {
+//   object: WaitlistEntryObject;
+//   id: string;
+//   emailAddress: string;
+//   status: WaitlistEntryStatus;
+//   /**
+//    * Indicates if the waitlist entry is locked. Locked entries are being processed in a batch action and are unavailable for other actions.
+//    *
+//    * @remarks
+//    */
+//   isLocked?: boolean | undefined;
+//   /**
+//    * Unix timestamp of creation.
+//    *
+//    * @remarks
+//    */
+//   createdAt: number;
+//   /**
+//    * Unix timestamp of last update.
+//    *
+//    * @remarks
+//    */
+//   updatedAt: number;
+//   invitation?: WaitlistEntryInvitation | null | undefined;
+// };

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

@@ -0,0 +1,27 @@
+import type { WaitlistEntryStatus } from './Enums';
+import { Invitation } from './Invitation';
+import type { WaitlistEntryJSON } from './JSON';
+
+export class WaitlistEntry {
+  constructor(
+    readonly id: string,
+    readonly emailAddress: string,
+    readonly status: WaitlistEntryStatus,
+    readonly invitation: Invitation | null,
+    readonly createdAt: number,
+    readonly updatedAt: number,
+    readonly isLocked?: boolean,
+  ) {}
+
+  static fromJSON(data: WaitlistEntryJSON): WaitlistEntry {
+    return new WaitlistEntry(
+      data.id,
+      data.email_address,
+      data.status,
+      data.invitation && Invitation.fromJSON(data.invitation),
+      data.created_at,
+      data.updated_at,
+      data.is_locked,
+    );
+  }
+}

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

@@ -34,6 +34,7 @@ export * from './User';
 export * from './Verification';
 export * from './SamlConnection';
 export * from './TestingToken';
+export * from './WaitlistEntry';
 
 export type {
   EmailWebhookEvent,