npm package: @shyntech-proximity/identities
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 Identity 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:**

* **Identity**: Contains identity_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. Identity Endpoints

### 3.1 Get Identity by ID

**GET** `/identity/:identityId`

| Parameter  | Type   | Required | Description       |
| ---------- | ------ | -------- | ----------------- |
| `identityId` | String | Yes      | Identity identifier |

**Response:** Identity object including `identity_info` and `inventory`.

**Error Codes:**

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

---

### 3.2 Get Identity by Phone Number

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

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

**Response:** Identity object.

**Error Codes:**

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

---

### 3.3 Create / Update / Delete Identity

| Method | Endpoint            | Request Body                                                                    | Response            | Notes                           |
| ------ | ------------------- | ------------------------------------------------------------------------------- | ------------------- | ------------------------------- |
| POST   | `/identity`           | `{ identity_id, name, address, contact, gps_location, opening_hours, inventory }` | 201, identity created | Create new identity               |
| PUT    | `/identity/:identityId` | `{ field: value, ... }`                                                         | 200, updated identity | Partial update supported        |
| DELETE | `/identity/:identityId` | None                                                                            | 200, deleted identity | Remove identity 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": "Identity not found"
}
```

---

## 5. Notes / Guidelines

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