AdrianArtiles/viral-waitlist-api

Viral Waitlist API Service

A simple GraphQL express API service to build your own headless viral waitlist.
Explore the docs »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgements

About The Project

I wanted to build a viral waitlist (where people can move up the waitlist by referring other people) for recent project.

I wanted to control the UX and experience, so I needed it as a headless API. There are a number of "viral waitlist as a service" services out there, but only few of them offered APIs, and none of them were good.

So I built my own real quick and this is it.

Through this service's API users can be added to the waitlist (with optional referral ID), confirm email addresses, and get a users position. It also has some common sense stuff like validating email addresses, rate limiting, and disallowing disposable email providers. That's pretty much it.

Built With

• Express
• Postgres
• Typescript
• TypeORM
• GraphQL
• Apollo
• Nodemailer

Getting Started

It's a single simple express server that uses Postgres for storing user data.

Ratelimiting is just done in memory, you'll want to add Redis if you have multiple servers running.

Prerequisites

• npm (v6 or greater)
• node (v12 or greater)
• postgres (v12 or greater)

Installation

1. Fork and clone this repo
2. Install NPM packages

   npm install

3. Copy .env.example to .env and update values
4. Create a postgres database (default name is waitlist_development)
5. Run npm build (does database migrations, etc.)

   npm run build

6. Update instances of "example" throughout the codebase with your URL / name (TODO: move this to env var)
7. Run locally

   npm run dev

Usage

The service is almost entirely used via the GraphQL API (can add a REST API if there's enough demand). There is a single endpoint at /confirmEmail used as a link in welcome emails to confirm their email address.

The GraphQL endpoint is at /graphql by default. The mutation signup takes the arguments of email (and optional referrerId which is the ID of the referring user). This returns the user which includes their position. This mutation is idempotent and can always be used to return a user's position (along with the user query).

When a user / email is signed up, they receive an email to confirm their email address. They confirm their email address by clicking on a link which takes them to /confirmEmail. Update the link they are emailed to your instance URL in src/libraries/nodemailer.ts. (TODO: update this to an env var).

Every 5 minutes all the users positions are updated (by the number of points/referrals they have, then by sign up time).

There is no functionality to remove people from the list or "invite" them. I just did this manually with direct access to the database.

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the GNU GPLv3 License. See LICENSE for more information.

Contact

Adrian Artiles - @AdrianArtiles

Project Link: https://github.com/AdrianArtiles/viral-waitlist-api