@smart-waitlist/client

Tiny, dependency-free client SDK for Smart-Waitlist waitlists.

The defining feature is preview mode: the SDK works before you have an account. With no project key it captures signups to localStorage, so a waitlist you just dropped into a page is functional immediately. Add a key later and the queue you already collected is imported to the server on first mount — nobody who signed up during preview is lost.

• Zero dependencies, ESM + CJS, full TypeScript types
• ~3.4 kB minified
• Works in any browser framework; no React required

Install

npm install @smart-waitlist/client

Using an AI editor (Cursor, Claude Code, Lovable)? You can skip the manual wiring:

add a waitlist with referral mechanics using smart-waitlist

Quick start

import { SmartWaitlistClient } from '@smart-waitlist/client';

// No key → preview mode. Signups go to localStorage.
const client = new SmartWaitlistClient();

const result = await client.signup({ email: '[email protected]' });
result.position; // 1
result.preview;  // true

Add a project key to switch to live capture. Nothing else changes:

const client = new SmartWaitlistClient({
  projectKey: process.env.NEXT_PUBLIC_SMARTWAITLIST_PROJECT_KEY,
});

client.mode; // 'live'

Get a free key at app.matekudasai.com.

Preview → live

Call syncPreviewQueue() once when the app mounts in live mode. It's a no-op in preview mode and when the queue is empty, so it's safe to call unconditionally:

useEffect(() => {
  client.syncPreviewQueue().catch(() => {});
}, [client]);

The local queue is cleared only after the server confirms the import, and the server de-duplicates by email against the existing waitlist — already-present addresses come back in skipped rather than creating a second row, so a double mount can't double-count anyone.

API

new SmartWaitlistClient(options?)

| Option | Type | Default | Notes | | ------------ | --------- | ----------------------------------- | -------------------------------------------------------- | | projectKey | string | — | Absent or empty → preview mode. | | apiUrl | string | https://app.matekudasai.com/api | Trailing slash is trimmed. | | storage | Storage | window.localStorage when present | Inject for tests or non-browser environments. |

client.mode is 'preview' or 'live' and is fixed at construction.

signup(input): Promise<SignupResult>

input is { email, metadata?, referredBy? }. In preview mode this resolves locally and never touches the network; duplicate emails return their existing position rather than a new one.

interface SignupResult {
  id: string;              // 'preview_…' in preview mode
  email: string;
  position: number;        // 1-based
  referralToken: string;
  referralLink: string | null; // null in preview mode
  verified: boolean;
  preview: boolean;
}

syncPreviewQueue(): Promise<{ imported: number; skipped: number }>

Imports the local preview queue. Returns { imported: 0, skipped: 0 } in preview mode.

getAccessStatus({ email }): Promise<AccessSnapshot>

The canonical "are they in?" check. Access is a live-only concept — preview mode always returns WAITING.

interface AccessSnapshot {
  email: string;
  accessStatus: 'WAITING' | 'GRANTED' | 'REVOKED';
  grantedAt: string | null;
}

getMetadata(): Promise<WaitlistMetadata | null>

Public-safe plan info. Returns null in preview mode. Use watermark to decide whether to render the "Powered by Smart-Waitlist" badge.

interface WaitlistMetadata {
  usedSignups: number;
  signupCap: number | null; // null = unlimited
  plan: 'FREE' | 'PAID';
  watermark: boolean;
  milestones: number[];
}

getPreviewSessionId(): string | null · getPreviewCount(): number

The stable preview session id (minted on first preview signup) and the current local queue size. Useful for building a "connect your waitlist" prompt that carries attribution.

Errors

Live-mode methods throw on a non-2xx response with the status included, e.g. Smart-Waitlist signup failed: 429. Preview-mode calls do not throw on the network because they never make one.

License

MIT