Perks Ledger
A personal credit card perks and benefits tracker. Track monthly credits, annual travel benefits, quarterly rewards, and card-year ROI across all your premium cards — with cloud sync, snooze, streak tracking, and fee-coverage analytics.
Live at: perks.hueyventures.org
Features
Tracking
- This Month — check off benefits as you use them; monthly, quarterly, semi-annual, and annual cadences all tracked per period
- Card Year view — full card-anniversary-aligned 12-month history and summary; year selector adapts to each card's renewal date
- YTD view — calendar-year history and summary (separate from card year)
- History Log — full timeline of benefit claims and missed credits
Analytics
- Year-end Projections — straight-line projection of captured value based on your current pace, per card
- ROI Grade — letter grade (A/B/C/D) based on projected capture vs annual fee
- Multi-year Trends — fee-relative bar chart showing captured vs fee across years
- Annual Recap — total captured, biggest miss, card streaks
- Keep / Cancel — data-driven renewal recommendation per card
- Benefit Digest — unified urgency dashboard: "Act now" list ranked by urgency × value (dismiss with ×, restore with shake/Undo), collapsed "By Deadline" buckets (monthly / quarterly / semi-annual / annual), and a collapsed "Dismissed" section with per-item Restore
- Portfolio Value — hero summary of total captured vs projected vs fees across all cards; per-card breakdown sorted by capture %; layered captured + projected progress bar
- Fee Optimizer — shows net impact of canceling each card (fee saved minus projected benefits lost), sorted by cancel-impact; portfolio-level net position + fee-coverage bar
- Card Simulator — "what if I added this card?" Projects annual value for any unowned card using your actual category capture rates (derived from existing card history), not a naive 100%. Shows grade A–D, net projected vs fee, a layered max-vs-projected progress bar, per-category behavior profile, and a per-benefit breakdown with claim-rate annotations
- Renewal Calendar + Fee Tracker — unified 12-month timeline of every card's annual-fee/anniversary date, grouped by month with days-until + a ▲ marker when a card raised its fee this year, plus a top alert ("⚠ N cards raised fees…") and a per-card mini fee-history sparkline
- Export Report — year-end benefits report with per-card Captured/Missed/Net vs Fee/Capture %/ROI grade, plus a one-click CSV download and a print stylesheet for "Save as PDF"
- Achievements — gamified badge system with 100+ badges across 5 tiers (Bronze / Silver / Gold / Platinum / Legendary). Categories: streaks, portfolio size, value captured, fee mastery, card mastery, claim volume, completionist, category specialists, and card-specific loyalty badges. Flip-card UI with locked/unlocked states; retroactive backfill on first sign-in; toast on unlock
- Compare Cards — side-by-side captured / projected / missed metrics
- Heatmap — benefit claim density view by month
Benefit control
- Snooze — hide any benefit from all calculations until a chosen month-year (⏸ button on hover). Global Entry / TSA PreCheck benefits get a "4 years" one-tap preset for the next eligibility window
- Skip — permanently exclude a benefit from a specific period (e.g. if you missed a deadline)
- Partial use — record partial redemption of credits (e.g. Chase $300 travel credit)
- Custom amounts — override a benefit's dollar amount (e.g. if your actual redemption value differs)
- Notes — attach a note to any benefit period (e.g. confirmation number, vendor)
- Credited — mark whether a statement credit has actually posted
Quality of life
- Dark / light mode — toggle in the menu; persists across sessions
- Confetti — fires once (desktop only) when a card crosses from fee owed into profit
- Pull to refresh — sync latest data from Supabase on mobile
- Swipe navigation — swipe left/right between the four main views on mobile
- Fee date overrides — set a custom anniversary month + day per card via the ✎ button
- Settings screen — profile name, password change, card selection
- Notifications — reminders before benefits expire: aggregate by cadence (monthly/quarterly/semi-annual) plus an opt-in per-benefit mode (e.g. "$10 Peloton Credit — 3 days left"). Local notifications, fire while the app is open; deduped per benefit/period
- Email Digest (optional) — opt-in weekly email summary of unclaimed benefits, sent via Supabase Edge Function (
send-weekly-digest) using Resend. Toggle in Settings → Notifications
- Background push (optional) — opt-in toggle delivers reminders even when the app is closed, via Supabase Edge Function (
send-push) on daily cron (requires VAPID keys + migration — see KNOWLEDGE.md)
- Card flip — tap a card image to flip to the back side showing points multipliers and current capture progress
- Installable PWA — add to home screen on iOS / Android; portrait lock; landscape side-rail nav
Calculation formulas
Effective fee
effective fee = annual fee − card-year captured
Where card-year captured = sum of all benefit amounts marked used across all past and current periods in the 12-month card year (benefit start month through anniversary month − 1).
Year-end projection
months elapsed = (current abs month) − (card year start abs month) + 1, clamped 1–12
months remaining = 12 − months elapsed
projected repeating = (repeating captured / months elapsed) × months remaining
projected = one-time captured + repeating captured + projected repeating
repeating = monthly + quarterly benefits; one-time = annual, semi-annual, etc.
ROI grade
Grade is based on projected / annual fee:
| Grade | Threshold |
|---|
| A | ≥ 100% |
| B | ≥ 80% |
| C | ≥ 50% |
| D | < 50% |
Card year start
A card year starts on the anniversary month/day. If today is before this year's anniversary date, the year started in the previous calendar year; if on or after, it started this calendar year.
Snooze exclusions
Snoozed benefits are excluded from: card-year captured, monthly available, year-end projection, ROI grade, priority queue, and all-cards summary. The snooze state syncs to Supabase so it persists across devices.
Cards supported
| Card | Key |
|---|
| Amex Platinum | platinum |
| Amex Gold | gold |
| Amex Green | green |
| Chase Sapphire Reserve | csr |
| Chase Sapphire Preferred | csp |
| Capital One Venture X | cap1_venture_x |
| Hilton Honors Aspire | ah |
| Marriott Bonvoy Brilliant | amb |
| Marriott Bonvoy Bevy | mbb |
| World of Hyatt | uq (note: uses uq key) |
| United Quest | uq |
| United Club Infinite | uc |
| Citi Strata Premier | csp2 |
| WF Autograph Journey | wfaj |
| Aeroplan Reserve | adr |
| Aeroplan | adp |
| Venture X Business | vxb |
| JetBlue Mastercard Reserve | jmr |
| US Bank Altitude Reserve | usbar |
Stack
| Layer | Tech |
|---|
| Frontend | Vanilla JS ES modules / HTML / CSS — no framework, no build step |
| Auth + Sync | Supabase (email/password auth, RLS, cloud data sync) |
| Hosting | Vercel with custom domain (perks.hueyventures.org) |
| Fonts | Inter + JetBrains Mono (Google Fonts) |
Module structure
index.html — app shell, modals, PWA meta
css/styles.css — all styles (dark + light mode, responsive, landscape)
js/
cards.js — card definitions: sections, benefits, amounts, cadences
state.js — shared state object, Supabase client, constants (CY, CM, CD)
storage.js — localStorage + Supabase sync; custom amounts, partial use,
notes, credited, skipped, snoozed, fee overrides
periods.js — period math: card year start, period generation, isPCurrent,
calcStats, projections, ROI grade, streaks
badges.js — achievement badge definitions (100+ badges, 5 tiers),
check/earn/persist/backfill logic, TIER_COLORS
views.js — all render functions (renderCurrent, renderROI, renderDigest,
renderNetValue, renderFeeOptimizer, renderCardSimulator, …)
main.js — auth flow, event handlers, navigation, modals, confetti,
renderBadgesView, email digest toggle, push subscribe
manifest.json — PWA manifest
sw.js — service worker (offline cache, currently v35)
supabase/
functions/send-weekly-digest/ — weekly email digest (Resend)
functions/send-push/ — web push notifications (web-push npm)
digest_migration.sql — adds digest_cache + digest_enabled to user_profiles
push_migration.sql — creates perks_push_subscriptions table
cron_schedule.sql — pg_cron for weekly digest
push_cron.sql — pg_cron for daily push at 16:00 UTC
Data & sync
All user data is stored in Supabase (tracker_data table) as a single JSON blob per user, merged with local localStorage on load. The payload includes:
[cardKey] — benefit check-off state (benefitId__periodKey: true/false)_customAmounts — per-benefit dollar overrides_partial — partial credit amounts_notes — period notes_credited — statement credit posted flags_skipped — period-level skips_snoozed — benefit-level snooze-until months (cardKey__benefitId: 'YYYY-MM')_feeOverrides — custom fee month/day per card
The Supabase anon key is safe to expose in frontend code — RLS policies restrict each row to its owner.
Do not commit a Supabase service role key.
Running locally
No build step required — it's plain ES modules. Serve from any static file server:
npx serve .
# or
python3 -m http.server 8080
file:// URLs won't work for ES modules. Supabase auth requires the origin to be whitelisted in your Supabase project under Authentication → URL Configuration.
