# 🐝 FormHive

**Open-source form backend as a service.** Collect form submissions from any website, view them in a beautiful dashboard, get webhook notifications, and block spam — all running on Cloudflare's edge network.

A self-hostable alternative to Formspree, Getform, and Basin.

![License](https://img.shields.io/badge/license-MIT-yellow)
![Cloudflare Workers](https://img.shields.io/badge/runs%20on-Cloudflare%20Workers-orange)
![D1 Database](https://img.shields.io/badge/database-Cloudflare%20D1-blue)

---

## ✨ Features

- **🔗 Simple API** — Point any HTML form or `fetch()` call at your endpoint
- **📊 Dashboard** — Beautiful dark-mode UI to view and manage submissions  
- **🛡️ Spam Filtering** — Honeypot fields + pattern-based detection built in
- **🔔 Webhooks** — Get notified on every submission (Slack, Discord, Zapier, etc.)
- **⚡ Edge-powered** — Runs on Cloudflare Workers (fast globally, free tier friendly)
- **🗄️ D1 Database** — Submissions stored in Cloudflare's serverless SQL
- **🔑 API Key Auth** — Secure dashboard access with bearer tokens
- **📱 Responsive** — Dashboard works on mobile
- **🚀 One-click deploy** — Set up in under 5 minutes
- **💸 Free tier** — Cloudflare's free tier covers most use cases

## 🚀 Quick Start

### 1. Clone & Setup

```bash
git clone https://github.com/kszongic/formhive.git
cd formhive
npm install -g wrangler
wrangler login
```

### 2. Create D1 Database & KV Namespace

```bash
wrangler d1 create formhive-db
wrangler kv:namespace create FORMHIVE_KV
```

Update the IDs in `wrangler.toml` with the output values.

### 3. Initialize Database

```bash
wrangler d1 execute formhive-db --file=schema.sql
```

### 4. Deploy

```bash
wrangler deploy
```

### 5. Setup Admin Account

```bash
curl -X POST https://your-worker.workers.dev/api/setup \
  -H "Content-Type: application/json" \
  -d '{"name": "Admin"}'
```

Save the returned API key! You'll need it for the dashboard.

### 6. Open Dashboard

Visit `https://your-worker.workers.dev` and enter your API key.

---

## 📝 Usage

### HTML Form

```html
<form action="https://your-worker.workers.dev/f/YOUR_FORM_ID" method="POST">
  <input type="text" name="name" placeholder="Name" required>
  <input type="email" name="email" placeholder="Email" required>
  <textarea name="message" placeholder="Message"></textarea>
  
  <!-- Honeypot spam trap (hidden from users) -->
  <input type="text" name="_honeypot" style="display:none">
  
  <button type="submit">Send</button>
</form>
```

### JavaScript (fetch)

```javascript
const response = await fetch('https://your-worker.workers.dev/f/YOUR_FORM_ID', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'John Doe',
    email: 'john@example.com',
    message: 'Hello from my website!'
  })
});

const result = await response.json();
// { ok: true, id: "submission-uuid" }
```

### Special Fields

| Field | Purpose |
|-------|---------|
| `_honeypot`, `_gotcha`, `_hp` | Spam honeypot (bots fill these, humans don't) |
| `_redirect` | Override redirect URL for this submission |

---

## 🔌 API Reference

All dashboard API calls require `Authorization: Bearer YOUR_API_KEY` header.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/setup` | First-time admin setup (no auth) |
| `POST` | `/f/:formId` | Submit a form (public, no auth) |
| `GET` | `/api/stats` | Dashboard statistics |
| `GET` | `/api/forms` | List all forms |
| `POST` | `/api/forms` | Create a new form |
| `GET` | `/api/forms/:id` | Get form details |
| `DELETE` | `/api/forms/:id` | Delete form + submissions |
| `GET` | `/api/forms/:id/submissions` | List submissions (paginated) |
| `DELETE` | `/api/submissions/:id` | Delete a submission |

### Create Form

```bash
curl -X POST https://your-worker.workers.dev/api/forms \
  -H "Authorization: Bearer fh_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contact Form",
    "webhook_url": "https://hooks.slack.com/xxx",
    "redirect_url": "https://mysite.com/thanks"
  }'
```

---

## 🏗️ Architecture

```
┌──────────────┐     ┌──────────────────────┐     ┌──────────┐
│  HTML Form   │────▶│  Cloudflare Worker    │────▶│  D1 (SQL)│
│  or fetch()  │     │  - Spam filtering     │     └──────────┘
└──────────────┘     │  - Rate limiting (KV) │     ┌──────────┐
                     │  - Webhook dispatch   │────▶│  Webhook  │
┌──────────────┐     │  - Dashboard API      │     └──────────┘
│  Dashboard   │◀───▶│  - Static site serve  │
│  (SPA)       │     └──────────────────────┘
└──────────────┘
```

## 📄 License

MIT — use it however you want.

---

**Built with ☕ and Cloudflare Workers.**