PerkAlert

Get reminded to open your rewards apps when you arrive at a restaurant that has a loyalty program. PerkAlert watches for the chains you care about and sends a notification the moment you're nearby — even when the app is closed.

Built with Expo (React Native), Supabase, and the Google Places API.

How it works

1. The app pulls a list of restaurant chains that have rewards programs from Supabase (reward_chains table).
2. It searches the Google Places API for nearby locations of those chains.
3. It registers OS-level geofences around them, so the OS wakes the app and fires a local notification when you arrive — handled by expo-location + expo-task-manager + expo-notifications.

Background alerts require a development build. In Expo Go you can use the whole app (onboarding, nearby-rewards list, settings) — only the background geofence notifications need a dev/EAS build, since Expo Go can't run custom background tasks.

Project structure

src/
  config.ts              env vars + tunable constants (radii, throttle)
  env.ts                 Expo Go detection
  types/                 shared TypeScript types
  services/
    rewardsApi.ts        Supabase client + reward-chain queries
    places.ts            Google Places (New) search + chain matching
    geofencing.ts        register/clear geofences (expo-location)
    geofenceTask.ts      background task that fires the notification
    notifications.ts     local notifications (expo-notifications)
  screens/               Onboarding, Home, Settings
supabase/
  setup.sql              one-paste schema + seed for the Supabase SQL Editor
  migrations/ seed.sql   the same, split for CLI users
scripts/
  check-supabase.mjs     verify the Supabase connection
  check-places.mjs       verify the Google Places key

Setup

Prerequisites

• Node.js 20.19.4+ or 22.13+ (Expo SDK 54 requirement)
• The Expo Go app on your phone (for quick testing)
• A Supabase project and a Google Maps Platform API key with Places API (New) enabled (billing required)

1. Install

npm install

2. Configure environment

cp .env.example .env

Fill in .env:

EXPO_PUBLIC_GOOGLE_PLACES_API_KEY=...   # Google Maps Platform key (starts with AIza)
EXPO_PUBLIC_SUPABASE_URL=...
EXPO_PUBLIC_SUPABASE_ANON_KEY=...        # the anon / public key

3. Set up the database

In the Supabase dashboard → SQL Editor, paste and run supabase/setup.sql. It creates the tables and seeds ~20 well-known reward chains.

4. Verify your credentials

npm run check:supabase   # → lists the seeded chains
npm run check:places     # → lists restaurants near a test point

5. Run

npx expo start

Scan the QR code with Expo Go.

License

All rights reserved (for now).