npm package: @shyntech-proximity/vendors
Description: **Base URL:** `/api` (example) **Auth:** Currently relies on device headers (`x-device-sig`, `x-ws-token`) and IP-based identification for proximity features.
Latest version: 1.0.4

# Proximity Vendor Backend API Documentation

**Base URL:** `/api` (example)
**Auth:** Currently relies on device headers (`x-device-sig`, `x-ws-token`) and IP-based identification for proximity features.

**Models:**

* **Vendor**: Contains vendor_info and inventory arrays.
* **DeviceScan**: Records devices’ last scan (SSID info, timestamp, etc.).

---

## 1. Common Headers

| Header         | Description                | Required                               |
| -------------- | -------------------------- | -------------------------------------- |
| `x-device-sig` | Unique device signature    | Optional (used in proximity detection) |
| `x-ws-token`   | Session or workspace token | Optional                               |
| `public_ip`    | Client IP address          | Optional                               |


---

## 3. Vendor Endpoints

### 3.1 Get Vendor by ID

**GET** `/vendor/:vendorId`

| Parameter  | Type   | Required | Description       |
| ---------- | ------ | -------- | ----------------- |
| `vendorId` | String | Yes      | Vendor identifier |

**Response:** Vendor object including `vendor_info` and `inventory`.

**Error Codes:**

| Status | Message               |
| ------ | --------------------- |
| 404    | Vendor not found      |
| 500    | Internal server error |

---

### 3.2 Get Vendor by Phone Number

**GET** `/vendor?phoneNumber=<phoneNumber>`

| Query Parameter | Type   | Required | Description           |
| --------------- | ------ | -------- | --------------------- |
| `phoneNumber`   | String | Yes      | Vendor contact number |

**Response:** Vendor object.

**Error Codes:**

| Status | Message                                 |
| ------ | --------------------------------------- |
| 400    | phoneNumber query parameter is required |
| 404    | Vendor not found                        |
| 500    | Internal server error                   |

---

### 3.3 Create / Update / Delete Vendor

| Method | Endpoint            | Request Body                                                                    | Response            | Notes                           |
| ------ | ------------------- | ------------------------------------------------------------------------------- | ------------------- | ------------------------------- |
| POST   | `/vendor`           | `{ vendor_id, name, address, contact, gps_location, opening_hours, inventory }` | 201, vendor created | Create new vendor               |
| PUT    | `/vendor/:vendorId` | `{ field: value, ... }`                                                         | 200, updated vendor | Partial update supported        |
| DELETE | `/vendor/:vendorId` | None                                                                            | 200, deleted vendor | Remove vendor and all inventory |

---

## 4. Error Response Format

| Field     | Type   | Description                                      |
| --------- | ------ | ------------------------------------------------ |
| `error`   | String | Error message                                    |
| `message` | String | Optional descriptive message for success/failure |

**Example:**

```json
{
  "error": "Vendor not found"
}
```

---

## 5. Notes / Guidelines

1. **Proximity detection:** `GET /vendors` uses device signature, token, or IP as a fallback to retrieve recent Wi-Fi scans.
2. **Bulk operations:** Partial success is possible; the response includes per-item update status.
3. **Consistency:** All update operations return the new state of the object after modification.
4. **Pagination:** Not implemented yet for search; consider adding `limit` and `offset` query params for large datasets.
5. **Logging:** Server logs device signatures and SSIDs for audit/debugging.