https://github.com/itshivams/slack-connect-backend
A lightweight Node.js (TypeScript) backend that powers Slack Connect, a demo application that lets users - connect, send messages and schedule.
https://github.com/itshivams/slack-connect-backend
express slack
Last synced: about 2 months ago
JSON representation
A lightweight Node.js (TypeScript) backend that powers Slack Connect, a demo application that lets users - connect, send messages and schedule.
- Host: GitHub
- URL: https://github.com/itshivams/slack-connect-backend
- Owner: itshivams
- License: apache-2.0
- Created: 2025-08-07T06:02:37.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-08-07T06:04:15.000Z (11 months ago)
- Last Synced: 2026-01-12T16:29:40.092Z (5 months ago)
- Topics: express, slack
- Language: TypeScript
- Homepage:
- Size: 27.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Slack Connect Backend
A lightweight Node.js (TypeScript) backend that powers **Slack Connect**, a demo application that lets users:
* Connect their Slack workspace via OAuth 2.0
* Send messages to any channel instantly
* Schedule messages for the future and manage (list/cancel) them
* Reliably deliver scheduled messages even after restarts
> **Tech stack:** Node.js · Express · TypeScript · LowDB (JSON) · node‑schedule · Axios · dotenv
---
## ✨ Architecture Overview
```
┌─────────────┐ OAuth ┌──────────────┐
│ Front‑end │ ────────────► │ Slack API │
└─────────────┘ auth code & tokens └──────────────┘
▲ ▲
│ REST (/messages/*) │ chat.postMessage
│ │
┌──────────────────────────────┐ │
│ Express API (this project) │◄───────────┘
│ • /auth/slack │
│ • /messages/send │
│ • /messages/schedule │
│ • /messages/scheduled │
│ │
│ Token store & Scheduler │
│ ───────────────────────── │
│ • LowDB (db.json) │
│ • node‑schedule jobs │
└──────────────────────────────┘
```
* **OAuth 2.0 Flow** – `/auth/slack` redirects the user to Slack’s consent page.
On callback, we exchange the code for `access_token` (and optionally `refresh_token`).
Tokens are stored per team and automatically refreshed when close to expiry.
* **Persistence** – LowDB writes a simple `db.json` file that holds `tokens[]` and `messages[]`.
This keeps the demo dependency‑free (no external DB). Swap‑in Mongo/SQL easily.
* **Scheduling** – On startup we scan pending messages and register one‑off `node‑schedule` jobs.
Each job refreshes the team’s token (if needed) and calls Slack `chat.postMessage`.
Cancelling simply marks the message `cancelled` and aborts the job.
---
## 🚀 Quick Start
1. **Clone**
```bash
git clone https://github.com/itshivams/slack-connect-backend.git
cd slack-connect-backend
```
2. **Install**
```bash
npm install
```
3. **Configure**
Copy `.env.example` to `.env` and fill in your Slack credentials:
```
SLACK_CLIENT_ID=...
SLACK_CLIENT_SECRET=...
SLACK_SIGNING_SECRET=...
BASE_URL=http://localhost:4000
PORT=4000
```
Create a Slack **App** → **OAuth & Permissions**
*Redirect URL:* `http://localhost:4000/auth/slack/callback`
4. **Run**
```bash
npm run dev # nodemon + ts-node
```
Server logs:
```
2025‑08‑07T09:32:10Z [app] Server listening on port 4000
```
---
## 🛠️ API Reference
| Method | Endpoint | Body / Query | Description |
| ------ | -------- | ------------ | ----------- |
| `GET` | `/auth/slack` | — | Redirects to Slack OAuth 2.0 consent |
| `GET` | `/auth/slack/callback` | `?code=` | Handles OAuth, saves tokens |
| `POST` | `/messages/send` | `{ teamId, channel, text }` | Send message immediately |
| `POST` | `/messages/schedule` | `{ teamId, channel, text, sendAt }` | Schedule UNIX epoch ms |
| `GET` | `/messages/scheduled` | — | List all scheduled jobs |
| `DELETE`| `/messages/scheduled/:id` | — | Cancel a pending job |
---
## 🧩 Folder Structure
```
src/
routes/ Express route handlers
services/ Slack API, scheduler, token logic
utils/ Logger, helpers
db.ts LowDB wrapper
index.ts App entrypoint
```
---
## 🧑💻 Dev Scripts
| Command | Description |
| ------- | ----------- |
| `npm run dev` | Start in watch mode (ts-node-dev) |
| `npm run build` | Compile TypeScript to `dist/` |
| `npm start` | Run compiled JS |
---
## 📚 Challenges & Learnings
* **Token longevity** – Slack’s classic tokens never expire, but granular‑scoped apps can.
Implemented generic refresh flow that will gracefully no‑op when `expires_in` is absent.
* **Job resilience** – Node process restarts wipe in‑memory timers.
Persisted jobs in DB and re‑hydrate at boot to guarantee delivery.
* **Minimalism vs. Scalability** – Chose LowDB + node‑schedule to keep the demo single‑file & docker‑friendly.
For production, swap in PostgreSQL + BullMQ/Redis for at‑least‑once delivery and retries.