Feature 01
WebView Authentication
Costco’s real login page loads inside a WebView. Injected JavaScript
patches fetch and XMLHttpRequest to watch the first authenticated
call Costco’s own frontend makes after sign-in, capturing the costco-x-authorization
bearer token and a per-session client-identifier via postMessage.
The app never renders its own login form and never touches a member’s credentials.
Feature 02
Windowed Sync Engine
Costco’s GraphQL API paginates receipts in date ranges. The sync engine breaks the
full two-year lookback into rolling 6-month windows and fetches each in sequence, then
pulls itemized detail only for receipts not already stored. Covers in-warehouse, gas
station, and car wash receipts.
Feature 03
Incremental Sync
A last_sync_cursor persisted in the local app_config table means
every sync after the first is incremental — only receipts newer than the last run are
requested. Upgrading to premium clears the cursor once, so the next sync backfills the
full history without ever re-fetching what’s already stored.
Feature 04
Fuzzy Search
A Fuse.js index is built in-memory from every item name in the database on load and
after each sync, debounced at 250ms. Results are grouped by item and sorted by most
recent purchase — so “eggs” finds every carton you’ve ever bought,
misspellings included.
Feature 05
Encrypted On-Device Storage
Receipts and line items are written to SQLite via @op-engineering/op-sqlite,
a JSI binding with no bridge overhead, behind versioned migrations applied automatically
on startup. The captured Costco session token lives separately in the OS keystore via
react-native-encrypted-storage.
Feature 06
Receipt Detail
Tap through from any search result or sync list entry to the full itemized receipt
— tender type, taxes, and instant-savings, exactly as it appeared on the warehouse
printout, reconstructed entirely from locally stored data.
Feature 07
Freemium Monetization
Free users get 3 searches a day and 3 months of history, with non-personalized AdMob
banner and app-open ads. A single non-consumable Google Play Billing purchase removes
both limits permanently — entitlement is verified against Play on every app open,
so it survives reinstalls.
Feature 08
Clean, Testable Architecture
Distinct layers for the API client, auth service, sync engine, database repositories,
search service, and Zustand stores — each independently testable. Screens consume
hooks (useSync, useSearch, useReceipts) that own
all the async state, keeping components thin.
Feature 09
Resilient Token Handling
The Costco bearer token expires roughly every 15 minutes. Rather than pretending to hold
a long-lived session, the app degrades gracefully on auth failure and routes the member
back to the WebView login to capture a fresh token — no silent data loss, no crash.
Feature 10
Simple, Focused Navigation
Two bottom tabs — Search and My Receipts — behind an auth gate that shows the
login stack until a valid session exists. No unnecessary screens, no onboarding funnel;
the app opens straight into the thing members came for.
