# Yaltopia Tickets App

Mobile companion to the Yaltopia Tickets web app: **Scan. Send. Reconcile.**  
React Native (Expo) with NativeWind (Tailwind), React Native Reusables (shadcn-style), and orange/black theme.

## Run

```bash
npm install
npm start
```

Then choose iOS, Android, or Web.

## API Reference

Backend API is described in **`swagger.json`** (Yaltopia Invoice System API). Base URLs:

- Local: `http://localhost:3001/api/v1`
- Production: `https://api.yaltopia.com/api/v1`

Auth: Bearer JWT in `Authorization` header.

---

## Integration Task List

Use this list to wire the app to the live API. Each item maps to swagger endpoints and app screens.

### Authentication

- [ ] **Auth API client** — Create `lib/api/auth.ts` (or use a shared client) with:
  - `POST /auth/register` — register
  - `POST /auth/login` — login (return access + refresh)
  - `POST /auth/refresh` — refresh token
  - `GET /auth/profile` — current user
  - `POST /auth/logout` — logout
  - `GET /auth/google`, `GET /auth/google/callback` — Google OAuth (if used)
- [ ] **Token storage** — Store access/refresh tokens securely (e.g. expo-secure-store); attach Bearer to requests.
- [ ] **Login screen** — Wire `app/login.tsx` to login/register and Google; on success navigate to `/(tabs)` and store tokens.
- [ ] **Auth guard** — Protect tab/stack routes: redirect to `/login` when unauthenticated; optional “Remember me”.

### User & Profile

- [ ] **Profile API** — `GET /users/me` in `lib/api/users.ts`; return type from swagger `UserResponseDto`.
- [ ] **Profile screen** — Load user via `/users/me` in `app/(tabs)/profile.tsx`; show name, email, language; “Manage” → `/notifications`.
- [ ] **Profile update** — If backend supports PATCH/PUT for profile, add form and wire in profile screen.

### Invoices

- [ ] **Invoices API** — `lib/api/invoices.ts`:
  - `GET /invoices` (with pagination, filters)
  - `GET /invoices/stats`
  - `GET /invoices/{id}`, `POST /invoices`, `PUT /invoices/{id}` (if needed)
  - `GET /invoices/{id}/pdf`, `PATCH /invoices/{id}/status`
  - `POST /invoices/share/email`, `POST /invoices/share/link`
- [ ] **Home screen** — Replace mock earnings/invoice list with `/invoices` and `/invoices/stats` (and dashboard metrics if used).
- [ ] **Invoice detail** — Add `app/invoices/[id].tsx` (or reuse share flow) for view/edit/PDF/share; wire to `GET /invoices/{id}` and PDF endpoint.

### Scan (Invoice & Payment Receipt)

- [ ] **Scan API** — `lib/api/scan.ts`:
  - `POST /scan/invoice` — upload image, return extracted invoice data (match swagger request/response).
  - `POST /scan/payment-receipt` — upload payment receipt image.
  - `GET /scan/images/invoice/{invoiceId}`, `GET /scan/images/payment/{paymentId}` if needed.
- [ ] **Scan screen** — In `app/(tabs)/scan.tsx`: camera or image picker → upload to `POST /scan/invoice`; show “Extracting…” then result; “Save as new” / “Match to existing” using invoices API.
- [ ] **Scan → invoice** — Create or update invoice from scan result; sync with `POST /invoices` or `PUT /invoices/{id}`.

### Proforma

- [ ] **Proforma requests API** — `lib/api/proforma-requests.ts`:
  - `GET /proforma-requests`, `POST /proforma-requests` (create)
  - `GET /proforma-requests/{id}`, `PUT /proforma-requests/{id}`
  - `POST /proforma-requests/{id}/items`, `GET /proforma-requests/{id}/items`; items CRUD if in swagger
  - `GET /proforma-requests/{id}/submissions`, `GET /proforma-requests/submissions/{id}`, revision/revise/close/cancel
  - `GET /proforma-requests/{id}/comparison-data` if used
- [ ] **Proforma list** — In `app/(tabs)/proforma.tsx`: replace mock with `GET /proforma-requests` (pagination, status filter); “Create new” → create request then navigate to detail.
- [ ] **Proforma detail** — In `app/proforma/[id].tsx`: load `GET /proforma-requests/{id}` and items; show submissions; “Send to contacts” → share link/email (use share endpoint or deep link from API).
- [ ] **Proforma PDF** — If swagger has `GET /proforma/{id}/pdf`, add “Download PDF” on detail.

### Payments & Payment Requests

- [ ] **Payments API** — `lib/api/payments.ts`:
  - `GET /payments` (with pagination, optional `invoiceId` filter)
  - `GET /payments/{id}`, `POST /payments` (create), `PUT /payments/{id}` (update)
  - `POST /payments/{id}/flag`, `POST /payments/{paymentId}/associate` (associate to invoice)
- [ ] **Payments list** — In `app/(tabs)/payments.tsx`: replace mock with `GET /payments`; show pending vs reconciled (e.g. by `invoiceId` or status from API).
- [ ] **Payment detail** — In `app/payments/[id].tsx`: load `GET /payments/{id}`; “Associate to invoice” → pick invoice (from `GET /invoices`) then `POST /payments/{paymentId}/associate`.
- [ ] **Payment request flow** — If “payment request” in product means creating a payment record for someone to pay: use `POST /payments` and any “request” endpoint from swagger; add screen or modal as needed.

### Notifications

- [ ] **Notifications API** — `lib/api/notifications.ts`:
  - `POST /notifications/subscribe` (push subscription payload)
  - `DELETE /notifications/unsubscribe/{endpoint}`
  - `GET /notifications` — list for current user
  - `GET /notifications/settings`, `PUT /notifications/settings`
  - `POST /notifications/invoice/{id}/reminder` (send reminder)
- [ ] **Notifications list** — In `app/notifications/index.tsx`: replace mock with `GET /notifications`; mark read if API supports it.
- [ ] **Notification settings** — In `app/notifications/settings.tsx`: load `GET /notifications/settings`, save with `PUT /notifications/settings` (invoice reminders, days before due, news, report ready).
- [ ] **Push subscription** — On login or app open, register device with `POST /notifications/subscribe` (Expo push token or web push); handle unsubscribe on logout.

### Dashboard & Reports (optional)

- [ ] **Dashboard API** — If used: `GET /dashboard/metrics`, `/dashboard/invoice-trends`, `/dashboard/revenue-trends`, `/dashboard/invoice-status`, `/dashboard/sales-purchase`, `/dashboard/scanned-invoices`.
- [ ] **Home dashboard** — Optionally show metrics/charts on Home from dashboard endpoints.
- [ ] **Reports** — `GET /reports`, `GET /reports/latest`, `POST /reports/generate`, `GET /reports/{id}/download`; add a “Reports” entry in Profile or a dedicated screen if needed.

### Share & Documents

- [ ] **Share API** — `GET /share`, `POST /share/email`, `GET /share/view/{token}`, `POST /share/{id}/deactivate`, `GET /share/{id}` if used for proforma/invoice sharing.
- [ ] **Documents API** — `POST /documents/upload`, `GET /documents`, `GET /documents/{id}/preview`, `GET /documents/{id}/download`; use for attachments or scanned files if applicable.

### General

- [ ] **API client** — Central `lib/api/client.ts`: base URL from env, `Authorization: Bearer`, error handling, 401 → refresh or redirect to login.
- [ ] **Environment** — `EXPO_PUBLIC_API_URL` or similar for API base; use in client.
- [ ] **Types** — Generate or copy DTOs from `swagger.json` (e.g. into `lib/api/types.ts`) for type-safe requests/responses.
- [ ] **Offline / sync** — Optional: queue scan and payment-associate actions when offline; sync when back online (per product spec).

---

## Screens (current)

| Route | Description |
|-------|-------------|
| `/(tabs)` | Bottom tabs: Home, Scan, Proforma, Payments, Profile |
| `/(tabs)/index` | Home — earnings summary, quick actions, invoice list |
| `/(tabs)/scan` | Scan invoice — camera placeholder, recent scans |
| `/(tabs)/proforma` | Proforma list — create, list requests; tap → detail |
| `/(tabs)/payments` | Payments — pending match, reconciled list; tap pending → detail |
| `/(tabs)/profile` | Profile — account, notifications link, login, logout |
| `/proforma/[id]` | Proforma request detail — items, send to contacts, submissions |
| `/payments/[id]` | Payment detail — associate to invoice |
| `/notifications` | Notifications list — link to settings |
| `/notifications/settings` | Notification settings — toggles |
| `/login` | Sign in — email/password, Google |

---

## Design

- **Primary:** Orange `#ea580c` (CTAs, active tab).
- **Navbar / tab bar:** Dark `#2d2d2d`; white/orange text.
- **Backgrounds:** White / light gray `#f5f5f5`.
- **Font:** DM Sans (or system fallback).

See project plan / `mobile.md` for full design system and copy.