`apps/mobile/README.md`

129 lines
# Homes on Spec — iOS App (apps/mobile)

Expo SDK 57 / React Native app for the App Store onboarding of homesonspec.com.
Four native tabs: Browse (WebView), Saved (native favorites), Map (native react-native-maps), Alerts (push opt-in).

## Prerequisites

- Node 22+, pnpm 11+
- Expo CLI 57: `npm install -g eas-cli` (for builds only; not needed for local dev)
- iOS Simulator (Xcode) or a physical iPhone

## Run locally

```bash
cd apps/mobile
pnpm install          # or: npm install
npx expo start        # press i for iOS Simulator
```

## Typecheck

```bash
cd apps/mobile
npx tsc --noEmit
```

## Run expo-doctor

```bash
cd apps/mobile
npx expo-doctor
```

---

## Gated Steps Checklist (ordered — Steve runs these)

### Step 1: Register Bundle ID in Apple Developer Portal
**One-time. Requires Steve's Apple login.**

1. Go to https://developer.apple.com/account/resources/identifiers/list
2. Add new Identifier → App ID → Explicit: `com.abrams.homesonspec`
3. Enable: Push Notifications (for Alerts tab)
4. Save.

Command: _(manual portal action — no CLI)_

---

### Step 2: Create App Record in App Store Connect
**One-time. Requires Steve's Apple login.**

1. Go to https://appstoreconnect.apple.com/apps
2. New App → iOS → Name: "Homes on Spec" → Bundle ID: `com.abrams.homesonspec`
3. SKU: `homesonspec-ios-v1`
4. Fill in listing copy from `APP-STORE-LISTING.md`
5. Upload screenshots (at minimum: Browse, Saved, Map, Alerts tabs — 6.7" and 6.5" sizes)

Command: _(manual portal action — no CLI)_

---

### Step 3: EAS Init (register project with Expo's build service)
**One-time. Requires EAS login (`eas login`).**

```bash
cd apps/mobile
npx eas-cli login        # sign in with your Expo account (agentabrams)
npx eas-cli init         # links this dir to your EAS project, writes projectId into app.json
```

After `eas init`, update `app.json` → `extra.eas.projectId` with the printed ID, and update `lib/notifications.ts` → `registerForPushNotifications` with the same projectId.

---

### Step 4: Replace Placeholder Assets
**Before production build.**

- `assets/icon.png` — 1024×1024 px, no rounded corners (Apple adds them), no transparency
- `assets/splash.png` — 1284×2778 px (iPhone 14 Pro Max size), brand blue background
- `assets/adaptive-icon.png` — 1024×1024 for Android

Current files are placeholder solid-blue PNGs. Replace with real artwork.

---

### Step 5: Production Build + Submit (the Turnkey Script)
**Requires App Store Connect API key (one-time download from ASC → Users & Access → Integrations → App Store Connect API).**

```bash
# From the monorepo root:
bash apps/mobile/finish-homesonspec-appstore.sh \
  ~/Downloads/AuthKey_XXXXXXXXXX.p8 \
  <KEY_ID> \
  <ISSUER_ID>
```

This script:
- Routes the key via secrets-manager (never echoes)
- Wires eas.json
- Runs `eas build --platform ios --profile production`
- **Prints but does NOT run** `eas submit`

To send to TestFlight after the build completes (Steve's final gate):
```bash
cd apps/mobile
npx eas-cli submit --platform ios --profile production --latest
```

---

## Architecture Notes

| Tab | Type | Data Source |
|-----|------|-------------|
| Browse | WebView (react-native-webview) | https://homesonspec.com |
| Saved | Native FlatList + AsyncStorage | On-device only |
| Map | Native MapKit (react-native-maps) | GET https://homesonspec.com/api/map |
| Alerts | Native UI + expo-notifications | On-device + Expo push token |

### Known TODOs / Wiring Needed

1. **Push backend endpoint** — `lib/notifications.ts` requests notification permission but deliberately does NOT mint a push token while `PUSH_BACKEND_READY` is `false`, because `getExpoPushTokenAsync()` transmits a device identifier to Expo and nothing can send a push yet. Wire `https://homesonspec.com/api/push/register`, uncomment the POST, and flip `PUSH_BACKEND_READY` to `true` **in the same change** (TK-10387).
2. **Map tap → native Save** — the Map tab's detail sheet shows a "View Details" button that deep-links via `Linking.openURL`. A future improvement: also offer "Save this Home" from the map callout (needs the same save bridge as the Browse tab).
3. **Real app icon + splash** — placeholder blue PNGs must be replaced before App Review.
4. ~~**EAS projectId**~~ — DONE. `app.json` carries the real projectId (`9d110d60-…`); `lib/notifications.ts` reads it from `expoConfig.extra.eas.projectId`. The `SET-AT-EAS-INIT` placeholder survives only in `finish-homesonspec-appstore.sh` as a guard. This line previously said otherwise and caused a downstream review to wrongly conclude push registration could never fire.
5. ~~**Privacy page**~~ — DONE. `https://homesonspec.com/privacy` returns 200 (verified 2026-09-04).
6. **Browse save bridge accuracy** — the JS injected into the WebView reads `h1` + `data-price` / `data-location` attributes for save metadata. These selectors should be verified against the live PDP markup and tightened if needed.