npm package: @shyntech-proximity/inventories
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

# Inventory 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                               |

---

## 2. Inventory Endpoints

### 2.1 Get Inventory by Item ID

**GET** `/inventory/:itemId`

| Parameter | Type   | Required | Description              |
| --------- | ------ | -------- | ------------------------ |
| `itemId`  | String | Yes      | Unique inventory item ID |

**Response:**

| Field    | Type   | Description                                 |
| -------- | ------ | ------------------------------------------- |
| `vendor` | Object | Vendor info containing `vendor_info` fields |
| `item`   | Object | Inventory item matching `itemId`            |

**Error Codes:**

| Status | Message                  |
| ------ | ------------------------ |
| 404    | Inventory item not found |
| 500    | Internal server error    |

---

### 2.2 Get Inventory by Proximity

**GET** `/inventory`

**Headers used:** `x-device-sig`, `public_ip`, `x-ws-token`

**Response:**

* List of vendors matching the last device scan SSIDs

| Field         | Type   | Description             |
| ------------- | ------ | ----------------------- |
| `vendor_id`   | String | Vendor identifier       |
| `vendor_name` | String | Name of vendor          |
| `address`     | String | Vendor address          |
| `inventory`   | Array  | List of inventory items |

**Error Codes:**

| Status | Message                                    |
| ------ | ------------------------------------------ |
| 404    | No recent proximity data found for this IP |
| 500    | Internal server error                      |

---

### 2.3 Search Inventory

**GET** `/search?query=<query>`

| Query Parameter | Type   | Required | Description                                                    |
| --------------- | ------ | -------- | -------------------------------------------------------------- |
| `query`         | String | Yes      | Fuzzy search term for inventory, vendor name, address, or tags |

**Response:**

| Field     | Type   | Description                    |
| --------- | ------ | ------------------------------ |
| `query`   | String | Search term                    |
| `results` | Array  | List of vendors matching query |

**Error Codes:**

| Status | Message                     |
| ------ | --------------------------- |
| 400    | Query parameter is required |
| 500    | Internal server error       |

---

### 2.4 Create / Update / Delete Inventory

| Method | Endpoint                           | Request Body                              | Response                      | Notes                        |
| ------ | ---------------------------------- | ----------------------------------------- | ----------------------------- | ---------------------------- |
| POST   | `/vendor/:vendorId/inventory`      | `{ item_id, name, category, price, ... }` | 200, added item               | Add single inventory item    |
| POST   | `/vendor/:vendorId/inventory/bulk` | `{ items: [{ item_id, name, ...}, ...] }` | 200, items added              | Add multiple inventory items |
| PUT    | `/inventory/:itemId`               | `{ field: value, ... }`                   | 200, updated item             | Update fields of single item |
| PUT    | `/inventory/:vendorId/bulk`        | `[ { item_id, field: value }, ... ]`      | 200, summary of updated items | Bulk update inventory items  |
| DELETE | `/inventory/:itemId`               | None                                      | 200, deleted item             | Delete single item           |
| DELETE | `/inventory`                       | `{ itemIds: [id1, id2, ...] }`            | 200, `deletedCount`           | Bulk delete items            |

---

## 3. Error Response Format

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

**Example:**

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

---

## 4. Notes / Guidelines

1. **Proximity detection:** `GET /inventory` 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.