QueueZero SDK

A cross-platform TypeScript SDK for viral waitlists. Works in browsers, Node.js, and any JavaScript runtime.

Installation

npm install queuezero

Quick Start

import { QueueZeroClient } from 'queuezero';

// Create a client for your campaign
const client = new QueueZeroClient('my-campaign', {
  apiUrl: 'https://api.queuezero.io',
});

// Join the waitlist
const result = await client.joinWaitlist('user@example.com', {
  role: 'Developer',
  company: 'Acme Inc'
});

console.log(`You are #${result.position} in line!`);
console.log(`Share your link: ${client.getReferralLink()}`);

React Integration

import { useWaitlist } from 'queuezero/react';

function WaitlistForm() {
  const { status, loading, error, join, getReferralLink } = useWaitlist('my-campaign');

  const handleSubmit = async (email: string) => {
    await join(email, { role: 'Developer' });
  };

  if (status) {
    return (
      <div>
        <p>You are #{status.position} in line!</p>
        <p>Your score: {status.priority_score} points</p>
        <p>Referrals: {status.referral_count}</p>
        <p>Share your link: {getReferralLink()}</p>
      </div>
    );
  }

  return (
    <form onSubmit={(e) => {
      e.preventDefault();
      handleSubmit(new FormData(e.currentTarget).get('email') as string);
    }}>
      {error && <p style={{ color: 'red' }}>{error.message}</p>}
      <input type="email" name="email" disabled={loading} placeholder="Enter your email" />
      <button type="submit" disabled={loading}>
        {loading ? 'Joining...' : 'Join Waitlist'}
      </button>
    </form>
  );
}

API Reference

QueueZeroClient

Constructor

new QueueZeroClient(campaignSlug: string, options?: QueueZeroConfig)

Option	Type	Default	Description
`apiUrl`	`string`	`http://localhost:3000`	API base URL
`baseUrl`	`string`	Current origin	Base URL for referral links
`storage`	`StorageAdapter`	Auto-detected	Custom storage adapter
`timeout`	`number`	`10000`	Request timeout in ms

Methods

`joinWaitlist(email, metadata?, referrerCode?)`

Submit to the waitlist.

const result = await client.joinWaitlist(
  'user@example.com',
  { role: 'CTO', company: 'Startup Inc' },
  'ABC123' // Optional referral code
);
// Returns: { token, referral_code, referral_link, position, priority_score }

`getPosition()`

Get current waitlist status.

const status = await client.getPosition();
// Returns: { position, priority_score, referral_count, referral_code, referral_link, status }

`getReferralLink()`

Get the user's shareable referral link.

const link = client.getReferralLink();
// Returns: "https://example.com?ref=ABC123" or null

`getReferralCode()`

Get just the referral code.

const code = client.getReferralCode();
// Returns: "ABC123" or null

`isJoined()`

Check if user has joined this campaign.

if (client.isJoined()) {
  const status = await client.getPosition();
}

`reset()`

Clear the session (logout).

await client.reset();

useWaitlist Hook (React)

const {
  // State
  loading,    // boolean - operation in progress
  status,     // UserStatus | null - current status
  error,      // Error | null - last error
  isJoined,   // boolean - has joined this campaign
  
  // Actions
  join,           // (email, metadata?, referrerCode?) => Promise<SubmitResponse | null>
  refresh,        // () => Promise<UserStatus | null>
  getReferralLink, // () => string | null
  reset,          // () => void
} = useWaitlist('campaign-slug', options);

Storage Adapters

The SDK automatically detects the environment and uses the appropriate storage:

Browser: localStorage
Node.js/SSR: In-memory storage

You can also provide a custom adapter:

import { QueueZeroClient, StorageAdapter } from 'queuezero';

class RedisStorageAdapter implements StorageAdapter {
  async get(key: string) { /* ... */ }
  async set(key: string, value: string) { /* ... */ }
  async remove(key: string) { /* ... */ }
}

const client = new QueueZeroClient('my-campaign', {
  storage: new RedisStorageAdapter(),
});

Types

All types are exported for TypeScript users:

import type {
  UserStatus,
  SubmitResponse,
  QueueZeroConfig,
  StorageAdapter,
  UserMetadata,
  LeadStatus,
} from 'queuezero';

License

MIT