feat: Add Waitlists methods to User Management

src/user-management/fixtures/list-waitlist-users.json

@@ -0,0 +1,19 @@
+{
+  "object": "list",
+  "data": [
+    {
+      "object": "waitlist_user",
+      "id": "wl_user_01H5JQDV7R7ATEYZDEG0W5PRYS",
+      "email": "marcelina.davis@example.com",
+      "state": "pending",
+      "approved_at": null,
+      "waitlist_id": "waitlist_01H5JQDV7R7ATEYZDEG0W5PRYS",
+      "created_at": "2026-08-04T02:07:19.911Z",
+      "updated_at": "2026-08-04T02:07:19.911Z"
+    }
+  ],
+  "list_metadata": {
+    "before": null,
+    "after": null
+  }
+}

src/user-management/fixtures/list-waitlists.json

@@ -0,0 +1,15 @@
+{
+  "object": "list",
+  "data": [
+    {
+      "object": "waitlist",
+      "id": "waitlist_01H5JQDV7R7ATEYZDEG0W5PRYS",
+      "created_at": "2026-08-04T02:07:19.911Z",
+      "updated_at": "2026-08-04T02:07:19.911Z"
+    }
+  ],
+  "list_metadata": {
+    "before": null,
+    "after": null
+  }
+}

src/user-management/fixtures/waitlist-user.json

@@ -0,0 +1,10 @@
+{
+  "object": "waitlist_user",
+  "id": "wl_user_01H5JQDV7R7ATEYZDEG0W5PRYS",
+  "email": "marcelina.davis@example.com",
+  "state": "pending",
+  "approved_at": null,
+  "waitlist_id": "waitlist_01H5JQDV7R7ATEYZDEG0W5PRYS",
+  "created_at": "2026-08-04T02:07:19.911Z",
+  "updated_at": "2026-08-04T02:07:19.911Z"
+}

src/user-management/fixtures/waitlist.json

@@ -0,0 +1,6 @@
+{
+  "object": "waitlist",
+  "id": "waitlist_01H5JQDV7R7ATEYZDEG0W5PRYS",
+  "created_at": "2026-08-04T02:07:19.911Z",
+  "updated_at": "2026-08-04T02:07:19.911Z"
+}

src/user-management/interfaces/create-waitlist-user-options.interface.ts

@@ -0,0 +1,23 @@
+export interface CreateWaitlistUserOptions {
+  /** The email address of the user joining the waitlist. */
+  email: string;
+  /**
+   * Additional key/value pairs collected with the waitlist user, up to 50
+   * keys of 40 characters with values of up to 600 characters. Stored on
+   * creation only — they are not returned by the API and are not updated
+   * for a user already on the waitlist.
+   */
+  additionalFields?: Record<string, string>;
+  /**
+   * Whether to send the waitlist confirmation email to the user. Defaults
+   * to false. The email is only sent when the user is newly added — not
+   * when they were already on the waitlist.
+   */
+  notify?: boolean;
+}
+
+export interface SerializedCreateWaitlistUserOptions {
+  email: string;
+  additional_fields?: Record<string, string>;
+  notify?: boolean;
+}

src/user-management/interfaces/index.ts

@@ -55,3 +55,7 @@ export * from './user.interface';
 export * from './user-api-key.interface';
 export * from './user-api-key-with-value.interface';
 export * from './verify-email-options.interface';
+export * from './create-waitlist-user-options.interface';
+export * from './list-waitlist-users-options.interface';
+export * from './waitlist.interface';
+export * from './waitlist-user.interface';

src/user-management/interfaces/list-waitlist-users-options.interface.ts

@@ -0,0 +1,14 @@
+import { PaginationOptions } from '../../common/interfaces';
+import { WaitlistUserState } from './waitlist-user.interface';
+
+export interface ListWaitlistUsersOptions extends PaginationOptions {
+  /** Filter waitlist users by their state. */
+  state?: WaitlistUserState;
+  /** Filter waitlist users by their exact email address. */
+  email?: string;
+}
+
+export interface SerializedListWaitlistUsersOptions extends PaginationOptions {
+  state?: WaitlistUserState;
+  email?: string;
+}

src/user-management/interfaces/waitlist-user.interface.ts

@@ -0,0 +1,35 @@
+export type WaitlistUserState = 'pending' | 'approved' | 'denied';
+
+export interface WaitlistUser {
+  /** Distinguishes the waitlist user object. */
+  object: 'waitlist_user';
+  /** The unique ID of the waitlist user. */
+  id: string;
+  /** The email address of the waitlist user. */
+  email: string;
+  /** The state of the waitlist user. */
+  state: WaitlistUserState;
+  /** The timestamp when the waitlist user was approved, or null if not yet approved. */
+  approvedAt: string | null;
+  /**
+   * The ID of the waitlist the user joined. null for legacy waitlist users
+   * created before waitlists had IDs, which belong to the environment's
+   * default waitlist.
+   */
+  waitlistId: string | null;
+  /** An ISO 8601 timestamp. */
+  createdAt: string;
+  /** An ISO 8601 timestamp. */
+  updatedAt: string;
+}
+
+export interface WaitlistUserResponse {
+  object: 'waitlist_user';
+  id: string;
+  email: string;
+  state: WaitlistUserState;
+  approved_at: string | null;
+  waitlist_id?: string | null;
+  created_at: string;
+  updated_at: string;
+}

src/user-management/interfaces/waitlist.interface.ts

@@ -0,0 +1,17 @@
+export interface Waitlist {
+  /** Distinguishes the waitlist object. */
+  object: 'waitlist';
+  /** The unique ID of the waitlist. */
+  id: string;
+  /** An ISO 8601 timestamp. */
+  createdAt: string;
+  /** An ISO 8601 timestamp. */
+  updatedAt: string;
+}
+
+export interface WaitlistResponse {
+  object: 'waitlist';
+  id: string;
+  created_at: string;
+  updated_at: string;
+}

src/user-management/serializers/create-waitlist-user-options.serializer.ts

@@ -0,0 +1,12 @@
+import {
+  CreateWaitlistUserOptions,
+  SerializedCreateWaitlistUserOptions,
+} from '../interfaces/create-waitlist-user-options.interface';
+
+export const serializeCreateWaitlistUserOptions = (
+  options: CreateWaitlistUserOptions,
+): SerializedCreateWaitlistUserOptions => ({
+  email: options.email,
+  additional_fields: options.additionalFields,
+  notify: options.notify,
+});

src/user-management/serializers/index.ts

@@ -29,3 +29,7 @@ export * from './update-user-password-options.serializer';
 export * from './user.serializer';
 export * from './user-api-key.serializer';
 export * from './user-api-key-with-value.serializer';
+export * from './create-waitlist-user-options.serializer';
+export * from './list-waitlist-users-options.serializer';
+export * from './waitlist.serializer';
+export * from './waitlist-user.serializer';

src/user-management/serializers/list-waitlist-users-options.serializer.ts

@@ -0,0 +1,15 @@
+import {
+  ListWaitlistUsersOptions,
+  SerializedListWaitlistUsersOptions,
+} from '../interfaces/list-waitlist-users-options.interface';
+
+export const serializeListWaitlistUsersOptions = (
+  options: ListWaitlistUsersOptions,
+): SerializedListWaitlistUsersOptions => ({
+  state: options.state,
+  email: options.email,
+  limit: options.limit,
+  before: options.before,
+  after: options.after,
+  order: options.order,
+});

src/user-management/serializers/waitlist-user.serializer.ts

@@ -0,0 +1,17 @@
+import {
+  WaitlistUser,
+  WaitlistUserResponse,
+} from '../interfaces/waitlist-user.interface';
+
+export const deserializeWaitlistUser = (
+  waitlistUser: WaitlistUserResponse,
+): WaitlistUser => ({
+  object: waitlistUser.object,
+  id: waitlistUser.id,
+  email: waitlistUser.email,
+  state: waitlistUser.state,
+  approvedAt: waitlistUser.approved_at,
+  waitlistId: waitlistUser.waitlist_id ?? null,
+  createdAt: waitlistUser.created_at,
+  updatedAt: waitlistUser.updated_at,
+});

src/user-management/serializers/waitlist.serializer.ts

@@ -0,0 +1,8 @@
+import { Waitlist, WaitlistResponse } from '../interfaces/waitlist.interface';
+
+export const deserializeWaitlist = (waitlist: WaitlistResponse): Waitlist => ({
+  object: waitlist.object,
+  id: waitlist.id,
+  createdAt: waitlist.created_at,
+  updatedAt: waitlist.updated_at,
+});