SDK

npm install @enlistdev/sdk

import { Enlist } from '@enlistdev/sdk';

const enlist = new Enlist({
  apiKey: process.env.ENLIST_API_KEY!, // required
  baseUrl: 'https://api.enlist.dev', // override for local dev
  timeoutMs: 15_000,
  fetch: globalThis.fetch, // injectable, for tests
});

const signup = await enlist.waitlists.addSignup(waitlistId, {
  email,
  referral_code: new URL(request.url).searchParams.get('ref') ?? undefined,
});

// Their own link, for the confirmation screen.
const shareUrl = `https://yoursite.com/?ref=${signup.referral_code}`;

import type { SlackIntegrationConfig } from '@enlistdev/sdk';

await enlist.integrations.put('slack', {
  config: {
    webhook_url: process.env.SLACK_WEBHOOK_URL!,
    events: ['signup.created', 'signup.removed'],
  },
});

await enlist.integrations.setEnabled('slack', false); // pause, reversibly

import type {
  Signup,
  SignupResult,
  WaitlistStats,
  FieldDefinition,
  Page,
  Integration,
  IntegrationCreated,
  IntegrationType,
  IntegrationEventType,
} from '@enlistdev/sdk';

interface SignupResult {
  id: string;
  position: number;
  total: number;
  referral_code: string; // this signup's own, to share
}

interface Signup {
  id: string;
  email: string;
  position: number;
  /** `max(1, position - referral_count * referral_bonus)`. Null when the waitlist has no referral_bonus set. */
  display_position: number | null;
  utm_source: string | null;
  referrer: string | null;
  referral_code: string; // their own code
  referral_count: number; // how many people joined with it
  referred_by: string | null; // signup id of whoever referred them
  metadata: Record<string, string>; // {} when none was provided at signup
  fields: Record<string, string | number | boolean>; // {} when no custom fields are defined
  created_at: string;
  email_status: string | null;
  email_delivered_at: string | null;
  email_opened_at: string | null;
  email_clicked_at: string | null;
}

interface WaitlistStats {
  waitlist_id: string;
  /** All time, whatever range was asked for. */
  total: number;
  /** Signups inside the returned range — what `daily` sums to. */
  range_total: number;
  /** The range actually used; clamped forward on plans with a history cap. */
  range_from: string;
  range_to: string;
  daily: { date: string; signups: number }[];
  by_source: { source: string; signups: number }[];
  email_engagement: {
    emails_sent: number;
    /** Integers 0–100, or null before any email has been sent. */
    delivery_rate: number | null;
    open_rate: number | null;
    click_rate: number | null;
  };
  growth: {
    last_7: number;
    prev_7: number;
    /** Percent change, or null when the prior window was empty. */
    delta: number | null;
  };
  /** Top 5, descending. Empty when no referrer was captured. */
  referrer_domains: { domain: string; signups: number }[];
  /** All-time signups that arrived via a referral link. */
  referred_count: number;
}

interface FieldDefinition {
  key: string;
  label: string;
  type: 'string' | 'number' | 'boolean';
  required: boolean;
  position: number;
}

type IntegrationType = 'webhook' | 'slack' | 'discord' | 'loops' | 'posthog' | 'kit';

type IntegrationEventType =
  | 'signup.created'
  | 'signup.removed'
  | 'signup.email_delivered'
  | 'signup.email_opened'
  | 'signup.email_clicked';

interface Integration {
  type: IntegrationType;
  enabled: boolean;
  created_at: string;
}

interface IntegrationCreated {
  type: IntegrationType;
  enabled: boolean;
  /** Only on the response that first creates a webhook without one. Null otherwise, and never retrievable again. */
  signing_secret: string | null;
}

import { EnlistError } from '@enlistdev/sdk';

try {
  await enlist.waitlists.addSignup(id, { email });
} catch (error) {
  if (error instanceof EnlistError && error.code === 'rate_limited') {
    await sleep((error.retryAfter ?? 60) * 1000);
  }
}