Egg Party 🥚🎉

Egg party is a Slack App for thanking teammates, raising chickens, and having a rowdy ol' time

---

Table of Contents

---

• Want to contribute?
• Setup
  • Set up your local .env / dotenv file
  • Set up your local SQL Database
  • Set up a Slack App for testing in Slack
• Slack Setup
  • Slack App Settings
  • Using your Local API with your Slack App
• Scripts
• Debugging
  • Visual Studio Code
• Common Errors
• Helpful Links

Want to contribute?

---

• Read: Contributing Guidelines
• Install all of the following:
  • SQL Server Express or your favorite SQL technology that TypeORM supports.
  • Node v10+
  • TypeORM CLI

Setup

---

1. Clone this repo
2. Run npm install
3. Set up your .env / dotenv file
4. Set up your local database
5. In a shell in Egg Party, run npm test to build the project and run the unit tests.
   • If your tests run and pass, WOO! 🎉💃
   • If they don't, check:
     • That you installed everything
     • The Troubleshooting section
     • Our GitHub project's issues
   • If all else fails, report an issue here. Sorry we couldn't get you fixed sooner 😢

Local Environment Config

Make a file called ".env" in project root, with these contents:

ENVIRONMENT="Local"

SLACK_CLIENT_ID=""     # CLIENT ID HERE
SLACK_CLIENT_SECRET="" # CLIENT SECRET HERE
SLACK_SIGNING_SECRET=""# SIGNING SECRET HERE

# For more information see https://typeorm.io/#/connection-options/common-connection-options
TYPEORM_CONNECTION="" # if you're using SQL Server, use "mssql"
TYPEORM_DATABASE="EggParty"
TYPEORM_ENTITIES="./dist/src/db/entities/*.entity.js"
TYPEORM_MIGRATIONS="./dist/src/db/migrations/*.js"
TYPEORM_HOST="localhost"
TYPEORM_USERNAME="admin"
TYPEORM_PASSWORD="password"

SQL Database Setup

1. Create a local SQL Database named EggParty
   • e.g. CREATE DATABASE EggParty;
2. Make sure your local database server has these features enabled:
   • SQL Server Auth
   • TCP/IP
3. Create a local SQL admin with the credentials in your .env file
4. Run npm run migration:run to set up the Egg Party schema in your local database.

Slack Setup

---

Something out of date? Click here to report an issue!

In order to run locally against Slack, you'll need:

• A Slack Workspace to test in (create one here), and
• A Slack App (create one here)

Slack App Setup

1. You should be taken to a Basic Information view after creating your app.
2. Scroll down to App Credentials, and copy these credentials to the .env file you created earlier:
   • Client ID > SLACK_CLIENT_ID
   • Client Secret > SLACK_CLIENT_SECRET
   • Signing Secret > SLACK_SIGNING_SECRET
3. From the Features sidebar, go to Oauth & Permissions.
4. For now, add a Redirect URL of https://www.egg-party.com/api/v1/slack/oauth/redirect.
5. Down in the Scopes view, add the following scopes:
   • channels:history
   • reactions:read
   • im:history
   • im:write
   • chat:write
6. From the Features sidebar, go to Event Subscriptions.
7. Turn Events on.
8. For now, put a Request URL of https://www.egg-party.com/api/v1/slack/events.
9. Down in the Subscribe to Bot Events view, add the following Bot User Events:
   • message.channels
   • message.im
   • reaction_added
10. From the Features sidebar, go to Interactive Components.
11. Turn Interactivity on.
12. For now, put a Request URL of https://www.egg-party.com/api/v1/slack/interactions.

Using your Local API with your Slack App

1. In a shell, run npm start to run your local API.
2. In another shell, run npm run tunnel to tunnel your local traffic to a public URL.
3. The URL printed by ngrok is a URL that Slack can use to interact with your local environment.
4. From the Features sidebar, go to Oauth & Permissions.
5. Replace the Redirect URL you added earlier with https://{{ngrokUrl}}/api/v1/slack/oauth/redirect
6. From the Features sidebar, go to Event Subscriptions.
7. Replace the Request URL you put earlier with https://{{ngrokUrl}}/api/v1/slack/events
8. From the Features sidebar, go to Interactive Components.
9. Replace the Request URL you put earlier with https://{{ngrokUrl}}/api/v1/slack/interactions
10. From the Features sidebar, go to Manage Distribution.
11. Click the Embeddable Slack Button to install your app to your workspace.
    • This should create a slack_team entry in your database, and redirect you to Egg Party in your Slack Workspace.

Scripts

---

Running
npm start npm run serve	Run the API locally, hot reload when you make typescript changes
Testing
npm test npm run test:single-run	Build & run all unit tests
npm run test:watch	Run all unit tests & re-run when you make changes
Utilities
npm run tunnel	Tunnel your local traffic to a public URL using `ngrok`. Use this to run locally against Slack.
Style / Linting
npm run style:fix	Formats your local codebase to the Google Typescript Style
Database
npm run migration:generate	Generate a TypeORM migration file based on changes made to entities since the last migration was made Usage note: you must pass the migration script a name for the migration e.g. npm run migration:generate -- -n AddCreatedDateColumn
npm run migration:run	Runs migrations against the database specified in .env

Debugging

---

Visual Studio Code

Run the command Debug: Start Debugging by pressing F5, by searching in the command palette (F1), or from the Debug panel (Ctrl/Cmd + Shift + D)

Common Errors

---

• Failed to connect to localhost:1433 - Could not connect (sequence)
  • Cause: TCP is not enabled or the SQL Server Browser Service is not running (Related: typeorm#2333)

Helpful Links:

---

• Making changes to the Guide Book? Use the Guide Book Template!