add readme

Apillon · Apr 8, 2024 · 1cc6037 · 1cc6037
1 parent 403d1a1
commit 1cc6037
Show file tree

Hide file tree

Showing 3 changed files with 167 additions and 11 deletions.
diff --git a/README.md b/README.md
@@ -1 +1,47 @@
-# ps-signup-email-airdrop
+# Apillon pre-built solution for NFT Email Signup Airdrop
+
+[![Twitter Follow](https://img.shields.io/twitter/follow/Apillon?style=social)](https://twitter.com/intent/follow?screen_name=Apillon)
+
+Simplify your NFT distribution process by easily distributing digital collectibles (NFTs) to users that can sign up using only their email addresses for a limited amount of NFTs with a waitlist with our solution.
+
+**Access an admin panel to:** - Track successful and unsuccessful NFT deliveries, along with linked wallets. - Automate email notifications with claim instructions for recipients.
+
+**Before getting started, ensure you have:**
+
+- Created NFT collection using Apillon.
+- Access to an email server's details.
+- A specialized Ethereum wallet for admin panel access.
+- Apillon API key and secret for connection.
+
+**Options for deployment:**
+
+- Run the front-end locally or host it on any website provider.
+- Utilize Apillon's hosting service, with GitHub actions setup available.
+- Run the back-end locally or via Docker, configuring files with collectible and email server details.
+
+## Getting started
+
+Solution consists of 2 main parts, Node.js backend APIs and Vue 3 frontend.
+
+### Basic
+
+If you have no experience with git and would still like to use our prebuilt solution, feel free to click the green button "Code" on the upper right corner of this repository and then selecting "Download ZIP".
+Once downloaded, the zip file includes all files you need to run the application. Before that happens you need to set up configuration as described in documentation.
+
+### Advanced
+
+1. Fork the repo
+2. Configure and modify APIs and website
+3. Deploy API to docker or any other server that can run node.js applications
+4. Deploy website to Apillon hosting
+
+## Documentation
+
+| Resource                       | Description              |
+| ------------------------------ | ------------------------ |
+| [Backend](backend/README.md)   | Docs for node.js backend |
+| [Frontend](frontend/README.md) | Docs from Vue 3 frontend |
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](/LICENSE) file for details.
diff --git a/backend/README.md b/backend/README.md
@@ -1,10 +1,49 @@
-# Pre-built solution for Sign-up Email Airdrop via Apillon API (backend)
+# Pre-built solution for Email sign upAirdrop via Apillon API (backend)
 
-//TODO: description
+This repository contains source code for Email sign up Airdrop API.
+
+## Getting Started
+
+This repository is configured to run with `npm`.
+
+### Prerequisites
+
+- Node.js v18.16.0 or higher
+- npm v8.4.0 or higher
+- Mysql database
+- SMTP mail server
+
+### Run locally
+
+First setup environment variables as described below then run:
+
+```sh
+npm install
+npm run dev
+```
+
+To run CRON job:
+
+```sh
+npm run cron
+```
+
+### Endpoints
+
+| Route                   | Description                                               | Authentication required |
+| ----------------------- | --------------------------------------------------------- | ----------------------- |
+| GET `/`                 | Return API status                                         | false                   |
+| POST `/login`           | Admin wallet login                                        | false                   |
+| POST `/users`           | User signup                                               | false                   |
+| POST `/users/create`    | Creates new users to airdrop nfts to                      | true                    |
+| POST `/users/claim`     | Endpoint for claim - Mint NFT to specified wallet address | true                    |
+| GET `/users`            | Gets a list of all users                                  | true                    |
+| GET `/users/:id`        | Gets specifics for one user                               | true                    |
+| GET `/users/statistics` | Gets airdrop statistics                                   | true                    |
 
 ## Environment variables
 
-For local development and running app you will need to configure some environment variables. List of all supported vars can be found in [`src/config/env.ts`](/src/config/env.ts). 
+For local development and running app you will need to configure some environment variables. List of all supported vars can be found in [`src/config/env.ts`](/src/config/env.ts).
 
 For local development you should create `.env` file. To run this app in Docker, you can create `.env.deploy` and `.env.sql.deploy` and use provided [`docker-compose.yml`](/docker-compose.yml)
 
@@ -24,7 +63,7 @@ MYSQL_USER: root
 MYSQL_PASSWORD: Pa55worD?! # set your DB password (same as in .env.sql.deploy)
 
 APP_URL: 'http://your-custom-url.com'  # set URL of your frontend application
-ADMIN_WALLET: # your EVM wallet address 
+ADMIN_WALLET: # your EVM wallet address
 
 # Apillon configuration
 # Create (free) account at https://apillon.io to and setup API key and NFT collection
@@ -33,11 +72,11 @@ APILLON_SECRET: # Apillon api key secret
 COLLECTION_UUID:  # Apillon NFT collection UUID
 
 # Your email server configuration
-SMTP_HOST: 
+SMTP_HOST:
 SMTP_PORT: '465'
-SMTP_USERNAME: 
-SMTP_PASSWORD: 
-SMTP_EMAIL_FROM: 
+SMTP_USERNAME:
+SMTP_PASSWORD:
+SMTP_EMAIL_FROM:
 SMTP_NAME_FROM: 'NFT Airdrop'
 
 # API configuration (you can just live it as it is or appropriate fix dockerfile and compose)
@@ -47,7 +86,7 @@ API_PORT: 3000
 # To Enable hCaptcha, register and get a secret. Remove or use blank if you don't need it.
 CAPTCHA_SECRET:
 
-#Number of hours user have to claim NFT, before they are removed from line and become un eligible to claim 
+#Number of hours user have to claim NFT, before they are removed from line and become un eligible to claim
 CLAIM_EXPIRES_IN: # default 72
 ```
 
@@ -60,6 +99,7 @@ MYSQL_ROOT_PASSWORD: Pa55worD?! # set your DB password (same as in .env.deploy)
 MYSQL_DATABASE: airdrop
 
 ```
+
 ## Deploying with docker
 
 Build docker image with script [`./build-image.sh`](/build-image.sh) script or by running docker build command, for example:
@@ -74,3 +114,34 @@ If you correctly setup .env files, you can run app in docker by running
 ```sh
 docker compose up -d
 ```
+
+## Automated testing
+
+In this prebuilt solution, we have limit our automated tests to basic end-to-end tests. Default testing framework for this project is [Jest](https://jestjs.io/docs/en/getting-started). Test are written in `tests` directory.
+
+For running tests, check if all environment variables with suffix `_TEST` are correctly set. If running locally, variables should be set in your `.env` file in root folder.
+
+```yml
+# TEST config
+MYSQL_HOST_TEST: 127.0.0.1
+MYSQL_DB_TEST: Poap_test
+MYSQL_USER_TEST:
+MYSQL_PASSWORD_TEST:
+MYSQL_POOL_TEST: 20
+```
+
+### Running API tests
+
+```ssh
+npm run test
+```
+
+To run single test
+
+```ssh
+npm run test -- <search pattern>
+```
+
+> note the blank space after `--`
+
+Search pattern is used to find file with test. You may use filename or part of filename, for example `login.test`
diff --git a/frontend/README.md b/frontend/README.md
@@ -1,4 +1,43 @@
-# Email airdrop prebuild solution
+# Pre-built solution for Email sign upAirdrop via Apillon API (frontend)
+
+This repository contains source code for Email sign up Airdrop website.
+
+## Overview
+
+Solution has 3 main parts. Admin dashboard, page for NFT claim and page for users to sign up for receiving an NFT.
+In admin dashboard, admin adds emails, see their status, statistic, ...
+
+In the sign up page the end users can solve captcha and add their email address to reserve an NFT or get added to the waitlist. Users have a limited amount of time to claim their NFT or the next in line gets it.
+
+Cron job runs in the background and sends claim email when time set for sending passes.
+
+Users receives an email that redirects him to the claim page. On the claim page he connects the wallets and triggers the claiming process on the backend.
+
+## Configuration
+
+In `lib/config/` we can find configs for different environments.
+
+```ts
+const config: ConfigInterface = {
+  APP_URL: 'http://localhost:3000',
+  API_BASE: 'http://localhost:3001',
+  CHAIN_ID: 1287,
+  CONTRACT_ADDRESS: null,
+  METADATA_BASE_URI: null,
+  METADATA_TOKEN: null,
+};
+```
+
+You need to update this config for a smoother frontend experience.
+
+- `APP_URL` presents the URL where the frontend website lives.
+- `API_BASE` presents the URL where backend (API) lives.
+- `CHAIN_ID` is the ID of the EVM chain that you NFTs are.
+- `CONTRACT_ADDRESS` is the onchain contract address of your NFT collection.
+- `METADATA_BASE_URI` presents the base uri where you NFTs metadata live (IPNS if created via apillon).
+- `METADATA_TOKEN` presents the JWT token of the NFTs metadata URI.
+
+If `METADATA_BASE_URI` and `METADATA_TOKEN` are not present, the website still works normally but the users need to have their metamask connected to load a NFT after it was minted.
 
 ## Stack