dunkirk.sh
this repo has no description
1# College Email Spam Filter
2
3Intelligent email classifier that automatically filters college marketing spam while keeping important emails in your inbox.
4
5**Current Performance**: 100% accuracy on 63 labeled emails
6
7## Quick Start
8
9```bash
10# Install dependencies
11bun install
12
13# Run tests
14bun test
15
16# Build Google Apps Script
17bun run gas build
18
19# Copy build/Code.gs and paste into Apps Script editor
20# https://script.google.com
21```
22
23## What Gets Filtered vs Kept
24
25### ✅ Kept in Inbox
26- Security alerts (password resets, account issues)
27- Application confirmations
28- Enrollment confirmations
29- Scholarships actually awarded
30- Financial aid offers ready to view
31- Dual enrollment course information
32- Accepted student portal access
33
34### 🗑️ Filtered Out
35- Marketing emails and newsletters
36- Unsolicited college outreach
37- Application reminders (haven't applied)
38- Scholarship eligibility (not awarded)
39- FAFSA reminders
40- Campus tours and events
41- Deadline extensions
42
43## How It Works
44
45**TypeScript → Google Apps Script Pipeline**
46
47```
48src/classifier.ts (Core classification logic - single source of truth)
49 ↓
50 ↓ imported by
51 ↓
52src/apps-script/wrapper.ts (Apps Script wrapper)
53 ↓
54 ↓ bun run gas (bundle with esbuild)
55 ↓
56build/Code.gs (Single-file Google Apps Script)
57 ↓
58 ↓ Manual copy/paste
59 ↓
60Google Apps Script → Gmail Auto-Filtering
61```
62
63**Key Improvement**: The classifier logic is now shared between local testing and Apps Script deployment. No more manual syncing!
64
65## Gmail Deployment
66
67```bash
68# 1. Build
69bun run gas build
70
71# 2. Copy build/Code.gs contents
72
73# 3. Paste into Google Apps Script
74# https://script.google.com
75
76# 4. Also paste scripts/export-from-label.gs
77```
78
79Once deployed:
801. Set `DRY_RUN = false` in the Apps Script editor
812. Run `setupTriggers()` to enable auto-filtering every 10 minutes
823. Run `ensureLabels()` to create required labels
83
84## Development Workflow
85
86### Improving the Classifier
87
88See [docs/WORKFLOW.md](docs/WORKFLOW.md) for detailed instructions.
89
90```bash
91# 1. Export emails from Gmail
92# Run exportEmailsToDrive() in Apps Script console
93
94# 2. Label them interactively
95bun run label new-emails.json
96
97# 3. Import and evaluate
98bun run import new-emails-labeled.json
99
100# 4. Update patterns in src/classifier.ts
101
102# 5. Test locally
103bun test
104
105# 6. Build and deploy
106bun run gas build
107# Copy build/Code.gs to Apps Script editor
108```
109
110### Adding New Patterns
111
1121. Edit `src/classifier.ts` - the single source of truth
1132. Add tests in `src/classifier.test.ts`
1143. Run `bun test` to verify
1154. Build and deploy: `bun run gas build` then copy to Apps Script
116
117**Note**: The Apps Script is automatically bundled from `src/classifier.ts` via `src/apps-script/wrapper.ts`
118
119## Project Structure
120
121```
122src/
123 apps-script/
124 wrapper.ts - Apps Script wrapper (imports classifier)
125 Code.ts - DEPRECATED (see wrapper.ts)
126 appsscript.json - Apps Script manifest
127 classifier.ts - Core classifier (SINGLE SOURCE OF TRUTH)
128 classifier.test.ts - Unit tests
129 types.ts - TypeScript types
130 evaluate.ts - Evaluation tool
131 label.ts - Interactive labeling CLI
132 import-labeled.ts - Import labeled emails
133 build-gas.ts - Build/deploy script (uses esbuild)
134
135scripts/
136 export-from-label.gs - Export emails from Gmail
137
138build/ - Generated (gitignored)
139 Code.gs - Bundled Apps Script
140 bundled.js - Intermediate bundle
141
142data/
143 labeled-emails.json - Main dataset (63 emails)
144 example-export.json - Example export
145
146tsconfig.apps-script.json - TypeScript config for Apps Script
147```
148
149## Commands
150
151```bash
152# Testing & Evaluation
153bun test - Run unit tests
154bun run evaluate - Evaluate on labeled dataset
155
156# Apps Script Deployment
157bun run gas build - Compile TypeScript → .gs
158
159# Labeling Workflow
160bun run label <file> - Label emails interactively
161bun run import <file> - Import labeled emails to dataset
162```
163
164## TypeScript Compilation
165
166Following [Google's official TypeScript guide](https://developers.google.com/apps-script/guides/typescript):
167
168- **Type safety**: Full `@types/google-apps-script` support
169- **Modern syntax**: ES6+ features (arrow functions, classes, etc.)
170- **Local development**: Edit with VS Code autocomplete
171- **Manual deployment**: Build locally, copy/paste to Apps Script
172- **Bundling**: esbuild bundles classifier + wrapper into single file
173- **Single source of truth**: `src/classifier.ts` used by both local tests and Apps Script
174
175Configuration:
176- `src/build-gas.ts` - Build script with esbuild bundler
177- `src/apps-script/wrapper.ts` - Apps Script wrapper that imports classifier
178
179## Metrics
180
181- **Accuracy**: 100% (63/63 emails correctly classified)
182- **Precision**: 100% (no false positives - no spam in inbox)
183- **Recall**: 100% (no false negatives - all important emails reach inbox)
184- **F1 Score**: 100%
185
186## Requirements
187
188- [Bun](https://bun.sh) - JavaScript runtime
189- Gmail account
190- Google account for Apps Script
191
192## License
193
194MIT
195
196## References
197
198- [Google Apps Script TypeScript Guide](https://developers.google.com/apps-script/guides/typescript)
199- [@types/google-apps-script](https://www.npmjs.com/package/@types/google-apps-script)