# Rules for every app

These rules apply to the driver, customer and restaurant apps. Each app file links here instead of repeating them.

## Requests

Base URL: `https://deliver-us-api.front.aait-d.com/api/v1`

| Header | Value |
| --- | --- |
| `Authorization` | `Bearer {token}` for the role of the screen (`CUSTOMER`, `VENDOR` or `DELIVERY`) |
| `Locale` | `en`, `ar`, `pl` or `uk`. Names and messages come back in that language. |

Error and success messages come back in the `Locale` language (`en`, `ar`, `pl`, `uk`), validation errors included (for example `code is required` / `الحقل code مطلوب`). Without the header they fall back to English.

## Errors

Every error body has a `message` string. Show it as it is unless a screen below says otherwise. Don't translate it again in the app.

❗ Never compare `message` with a fixed string (like `== "not_enough_balance"`): it changes with the language. Decide by HTTP status, or check the condition before the call.

```json
{ "message": "Phone already in use" }
```

Some errors also carry `data`:

| Status | Meaning | `data` |
| --- | --- | --- |
| `400` | Invalid request, or a business rule refused it | Sometimes, e.g. field details |
| `401` | Not logged in, session ended, or the account cannot log in | Driver login: `{ "status", "reason" }` (see driver app, section 2) |
| `403` | Logged in, but not allowed to do this | — |
| `412` | Account exists but the phone is not verified yet | `{ "deliveryId" or "storeId", "phone" }` |

On a `401` after login, log the user out and open the login screen.

## Pushes

An FCM message is `notification.title` and `notification.body`. Most pushes have an empty `data` map, so no `event`, `key`, `action`, or order id. The names in the app files (`ORDER.DELIVERY.AVAILABLE`, `ORDER.DELIVERY.ASSIGN`, `ORDER.UPDATE`, `CUSTOMER.ARRIVE`) are the server events that choose the title and body. They are not a field the app can read. On tap, open the app and reload the orders screen for that role.

These pushes carry `data` (title and body in English; the in-app notification from `GET /app-notification` is in the `Locale` language):

| `data.type` | Other `data` | App does |
| --- | --- | --- |
| `DRIVER_TIER_CHANGED` | — | Reload `GET /user/profile` (tier and terms) |
| `WITHDRAW_STATUS` | `withdrawId`, `status` | Reload `GET /delivery/wallet` and the withdraw request |
| `REFUND_STATUS` (customer) | `orderId`, `refundRequestId`, `status` (`APPROVED` / `REJECTED`) | Reload the order, the refund request and the wallet |

## Order money fields

Some field names don't match their meaning. **`finalPrice` is not the amount to pay.** Use this everywhere an order is shown (`POST /order` response, `GET /order`, `GET /order/{id}`):

| Field | Meaning | Show it as |
| --- | --- | --- |
| `price` | Products total (offers on items already taken off) | "Products" |
| `productDiscount` | What item offers saved. Already inside `price` | Optional "You saved". Don't subtract it again |
| `tax` | Tax | "Tax" |
| `shipping` | Delivery fee charged. `0` when delivery is free | "Delivery" |
| `discountAmount` | Coupon discount | "Coupon" as a negative line. `0` = hide |
| `paidWithWallet` | Part paid from the customer wallet | "Paid from wallet" as a negative line. `0` = hide |
| `finalPrice` | Order value **before** coupon and wallet: `price + tax + shipping` | Not an amount to pay |
| `totalPrice` | **Still to pay** by cash or card: `finalPrice − discountAmount − paidWithWallet`, never below 0 | "Total to pay" |

Never compute the total in the app. The driver app reads `paymentMode` / `collectAmount` for what to collect ([driver app](driver-app.md)). No commission is ever added for the customer: the store and delivery commissions come off the store's and the driver's share.

## Loading

Stop the loader in `finally` on every path: success, any `4xx` or `5xx`, network failure, cancellation. A multipart request answers only after all files have uploaded, so a validation error can arrive late. Validate fields on the device before starting an upload.

## Phone format

The API accepts and stores a phone only in this exact shape:

```text
^\+\d{1,3}\s\d{8,10}$        e.g. +966 512345678
```

- `+`, a 1–3 digit country code, **one space**, then 8–10 digits.
- `+966512345678` (no space) is rejected with `400`: `enter valid phone like this +999 999999999`.
- The stored string is compared exactly. Send the same string on register, OTP, login and forgot-password.

Build it with one shared helper:

```text
phone = "+" + phoneCode + " " + nationalNumber     // national number: digits only
```

### Country code picker

Do not lock the code to `+966`. Load the list (no token needed):

```
GET /country?limit=100
```

| Field | Use |
| --- | --- |
| `name` | Picker label, in the `Locale` language |
| `phoneCode` | Digits only. Show as `+{phoneCode}`. |
| `phoneLength` | Number of digits the national number must have |

Select Saudi Arabia (`966`) when it is in the list, otherwise the first row. Limit the number field to `phoneLength`.

## Currency

Do **not** hardcode "Saudi Riyal", `SAR`, or `ر.س`. Load the platform currency (no token needed):

```
GET /settings?domain=BUSINESS
```

| `setting` | Use |
| --- | --- |
| `generalCurrencyCode` | ISO code, e.g. `PLN`, `SAR` |
| `generalCurrencySymbol` | Short symbol for amounts, e.g. `zł`, `ر.س` |
| `generalCurrencyNameEn` / `generalCurrencyNameAr` | Full name for placeholders (Price / Discount fields) |
| `generalCurrencyPosition` | `LEFT` or `RIGHT` of the amount |

Values are strings. Pick the name for the current `Locale` (`En` / `Ar`; for `pl`/`uk` show `generalCurrencySymbol` or `generalCurrencyCode` if you have no translated name yet). On product add/edit, use that name or symbol as the price/discount hint — never a fixed Riyal label.

## Images

The server stores uploaded images as received. Compress every image before adding it to the request. Do not send camera or gallery originals. Do not compress videos (reels and advertisement `video`).

| | |
| --- | --- |
| Longest side | 1280 px (never upscale) |
| Format | JPEG, `image/jpeg` |
| Quality | 70 |
| Expected size | about 200–400 KB |

One helper for every picker (Flutter):

```dart
Future<MultipartFile> compressedImage(String sourcePath, String fieldName) async {
  final targetPath = '${Directory.systemTemp.path}/$fieldName.jpg';
  final compressed = await FlutterImageCompress.compressAndGetFile(
    sourcePath,
    targetPath,
    minWidth: 1280,   // in this library these are the maximum output size
    minHeight: 1280,
    quality: 70,
    format: CompressFormat.jpeg,
  );
  return MultipartFile.fromFile(
    compressed?.path ?? sourcePath,
    filename: '$fieldName.jpg',
    contentType: MediaType('image', 'jpeg'),
  );
}
```

Image paths in responses (e.g. `image`, `photo`, `logo`) are server paths, shown the same way as every other image in the app.
