@shyntech-proximity/inventories 1.0.2 → 1.0.4

package/docs/QA.md

@@ -0,0 +1,215 @@
+# 🧪 QA Test Matrix
+
+## Proximity Inventory Backend Service (Inventory Domain)
+
+---
+
+## 1. Test Coverage Overview
+
+| Area                          | Covered |
+| ----------------------------- | ------- |
+| Proximity inventory discovery | ✅       |
+| Inventory lookup              | ✅       |
+| Inventory search              | ✅       |
+| Vendor inventory retrieval    | ✅       |
+| Inventory CRUD                | ✅       |
+| Bulk inventory operations     | ✅       |
+| Error handling                | ✅       |
+| Non-functional constraints    | ✅       |
+
+---
+
+## 2. Proximity Inventory Discovery Tests
+
+### Endpoint: `GET /inventory`
+
+| Test ID | Scenario                   | Preconditions                | Input                | Expected Result                      |
+| ------- | -------------------------- | ---------------------------- | -------------------- | ------------------------------------ |
+| P-01    | Valid proximity match      | DeviceScan exists with SSIDs | Valid device headers | 200, list of vendors                 |
+| P-02    | No proximity data          | No DeviceScan for device     | Valid headers        | 404, error message                   |
+| P-03    | Multiple SSID matches      | Scan overlaps >1 vendor      | Valid headers        | 200, multiple vendors                |
+| P-04    | Header priority resolution | All headers present          | All headers          | Device resolved using priority order |
+| P-05    | Fallback to socket IP      | No headers present           | None                 | Uses socket IP                       |
+| P-06    | Empty SSID list            | Scan exists but no SSIDs     | Valid headers        | 200, empty vendor list               |
+| P-07    | Server failure             | DB unavailable               | Valid headers        | 500                                  |
+
+---
+
+## 3. Inventory Item Lookup Tests
+
+### Endpoint: `GET /inventory/:itemId`
+
+| Test ID | Scenario           | Preconditions              | Input          | Expected Result               |
+| ------- | ------------------ | -------------------------- | -------------- | ----------------------------- |
+| I-01    | Valid item lookup  | Item exists                | Valid itemId   | 200, vendor + item            |
+| I-02    | Item not found     | Item absent                | Invalid itemId | 404                           |
+| I-03    | Duplicate item IDs | Same itemId across vendors | Valid itemId   | First matched vendor returned |
+| I-04    | Malformed itemId   | Invalid format             | Malformed ID   | 404                           |
+| I-05    | DB error           | DB failure                 | Valid itemId   | 500                           |
+
+---
+
+## 4. Inventory Search Tests
+
+### Endpoint: `GET /search?query=...`
+
+| Test ID | Scenario             | Preconditions        | Input            | Expected Result    |
+| ------- | -------------------- | -------------------- | ---------------- | ------------------ |
+| S-01    | Match inventory name | Matching item exists | `query=name`     | 200, matched items |
+| S-02    | Match category       | Category exists      | `query=category` | 200                |
+| S-03    | Match tags           | Tag exists           | `query=tag`      | 200                |
+| S-04    | Match vendor name    | Vendor matches       | `query=vendor`   | Vendor returned    |
+| S-05    | Match vendor address | Address matches      | `query=address`  | Vendor returned    |
+| S-06    | Case-insensitive     | Mixed case           | `query=MiXeD`    | Match returned     |
+| S-07    | No matches           | No matching fields   | `query=zzz`      | 200, empty results |
+| S-08    | Empty query          | —                    | `query=`         | 400                |
+| S-09    | Missing query        | —                    | No query param   | 400                |
+| S-10    | Special characters   | Regex-safe input     | `query=@#$`      | 200 or empty       |
+
+---
+
+## 5. Vendor Inventory Retrieval Tests
+
+### Endpoint: `GET /vendor/:vendorId/inventory`
+
+| Test ID | Scenario                 | Preconditions   | Input            | Expected Result      |
+| ------- | ------------------------ | --------------- | ---------------- | -------------------- |
+| V-01    | Valid vendor inventory   | Vendor exists   | Valid vendorId   | 200, inventory array |
+| V-02    | Vendor with no inventory | Empty inventory | Valid vendorId   | 200, empty array     |
+| V-03    | Vendor not found         | Vendor missing  | Invalid vendorId | 404                  |
+| V-04    | Malformed vendorId       | Invalid format  | Malformed ID     | 404                  |
+| V-05    | DB failure               | DB unavailable  | Valid vendorId   | 500                  |
+
+---
+
+## 6. Single Inventory CRUD Tests
+
+### 6.1 Add Inventory Item
+
+**POST `/vendor/:vendorId/inventory`**
+
+| Test ID | Scenario          | Preconditions    | Input           | Expected Result      |
+| ------- | ----------------- | ---------------- | --------------- | -------------------- |
+| C-01    | Add valid item    | Vendor exists    | Valid item body | 200, item added      |
+| C-02    | Vendor not found  | Vendor absent    | Valid body      | 404                  |
+| C-03    | Duplicate item_id | Same item exists | Same item_id    | 200 (no enforcement) |
+| C-04    | Missing item_id   | —                | Invalid body    | 200 or schema error  |
+| C-05    | DB failure        | DB unavailable   | Valid body      | 500                  |
+
+---
+
+### 6.2 Update Inventory Item
+
+**PUT `/inventory/:itemId`**
+
+| Test ID | Scenario          | Preconditions  | Input                 | Expected Result             |
+| ------- | ----------------- | -------------- | --------------------- | --------------------------- |
+| C-06    | Partial update    | Item exists    | `{ price }`           | 200, price updated          |
+| C-07    | Multiple fields   | Item exists    | `{ price, quantity }` | 200                         |
+| C-08    | Item not found    | Item absent    | Valid body            | 404                         |
+| C-09    | Empty update body | Item exists    | `{}`                  | 200, no change              |
+| C-10    | Invalid field     | Item exists    | `{ foo: 1 }`          | Field added (no validation) |
+| C-11    | DB failure        | DB unavailable | Valid body            | 500                         |
+
+---
+
+### 6.3 Delete Inventory Item
+
+**DELETE `/inventory/:itemId`**
+
+| Test ID | Scenario          | Preconditions   | Input          | Expected Result     |
+| ------- | ----------------- | --------------- | -------------- | ------------------- |
+| C-12    | Delete valid item | Item exists     | Valid itemId   | 200                 |
+| C-13    | Item not found    | Item missing    | Invalid itemId | 404                 |
+| C-14    | Multiple vendors  | Item duplicated | Valid itemId   | First match deleted |
+| C-15    | DB failure        | DB unavailable  | Valid itemId   | 500                 |
+
+---
+
+## 7. Bulk Inventory Operations Tests
+
+### 7.1 Bulk Add
+
+**POST `/vendor/:vendorId/inventory/bulk`**
+
+| Test ID | Scenario           | Preconditions  | Input         | Expected Result |
+| ------- | ------------------ | -------------- | ------------- | --------------- |
+| B-01    | Add multiple items | Vendor exists  | Valid items[] | 200             |
+| B-02    | Empty items array  | —              | `items: []`   | 400             |
+| B-03    | Invalid items type | —              | `items: {}`   | 400             |
+| B-04    | Vendor not found   | Vendor missing | Valid items   | 404             |
+| B-05    | DB failure         | DB unavailable | Valid items   | 500             |
+
+---
+
+### 7.2 Bulk Update
+
+**PUT `/inventory/:vendorId/bulk`**
+
+| Test ID | Scenario          | Preconditions    | Input          | Expected Result      |
+| ------- | ----------------- | ---------------- | -------------- | -------------------- |
+| B-06    | All items updated | Items exist      | Valid updates  | 200                  |
+| B-07    | Partial match     | Some items exist | Mixed item_ids | 200, partial success |
+| B-08    | No items array    | —                | `{}`           | 400                  |
+| B-09    | Empty array       | —                | `[]`           | 400                  |
+| B-10    | Vendor not found  | Vendor absent    | Valid array    | 404                  |
+| B-11    | Invalid fields    | Item exists      | `{ foo }`      | Field added          |
+| B-12    | DB failure        | DB unavailable   | Valid array    | 500                  |
+
+---
+
+### 7.3 Bulk Delete
+
+**DELETE `/inventory`**
+
+| Test ID | Scenario              | Preconditions    | Input           | Expected Result |
+| ------- | --------------------- | ---------------- | --------------- | --------------- |
+| B-13    | Delete multiple items | Items exist      | Valid itemIds[] | 200             |
+| B-14    | Partial delete        | Some items exist | Mixed itemIds   | 200             |
+| B-15    | Empty array           | —                | `itemIds: []`   | 400             |
+| B-16    | Invalid type          | —                | `itemIds: {}`   | 400             |
+| B-17    | DB failure            | DB unavailable   | Valid itemIds   | 500             |
+
+---
+
+## 8. Non-Functional Test Matrix
+
+### Performance
+
+| Test ID | Scenario                 | Metric        | Expected |
+| ------- | ------------------------ | ------------- | -------- |
+| N-01    | Inventory lookup         | Response time | < 500ms  |
+| N-02    | Search with many vendors | Response time | < 500ms  |
+| N-03    | Bulk update (100 items)  | Completion    | < 2s     |
+
+---
+
+### Scalability & Integrity
+
+| Test ID | Scenario             | Expected Result          |
+| ------- | -------------------- | ------------------------ |
+| N-04    | Concurrent updates   | No document corruption   |
+| N-05    | Partial bulk failure | Successful items persist |
+| N-06    | Large inventory      | No DB write errors       |
+
+---
+
+## 9. Known Risk Areas for QA
+
+| Risk                      | Why It Matters                     |
+| ------------------------- | ---------------------------------- |
+| No uniqueness enforcement | Duplicate item IDs possible        |
+| Regex search              | Performance degradation            |
+| Embedded inventory        | MongoDB document size limits       |
+| No auth                   | Cross-vendor modification possible |
+
+---
+
+## 10. QA Execution Guide
+
+| Role         | Focus Areas                    |
+| ------------ | ------------------------------ |
+| Manual QA    | Search, proximity, error flows |
+| Automation   | CRUD, bulk ops, regression     |
+| Load Testing | Search & bulk updates          |
+

package/docs/SRS.md

@@ -0,0 +1,311 @@
+# Software Requirements Specification (SRS)
+
+## Proximity Inventory Backend Service
+
+### **Inventory Domain Only**
+
+---
+
+## 1. Introduction
+
+### 1.1 Purpose
+
+This document specifies the functional and non-functional requirements for the **Inventory domain** of the Proximity Inventory Backend Service.
+
+The Inventory module enables:
+
+* Vendor-linked inventory storage
+* Proximity-based inventory discovery
+* Text-based inventory search
+* Single and bulk inventory management operations
+
+---
+
+### 1.2 Intended Audience
+
+| Audience                    | Usage                                    |
+| --------------------------- | ---------------------------------------- |
+| Product & Business          | Understand inventory capabilities        |
+| Backend Engineers           | Implement & maintain inventory APIs      |
+| Frontend / Mobile Engineers | Integrate inventory views & flows        |
+| QA / Test Engineers         | Validate inventory behavior & edge cases |
+
+---
+
+### 1.3 Scope
+
+| In Scope                            | Out of Scope                   |
+| ----------------------------------- | ------------------------------ |
+| Inventory CRUD (single & bulk)      | Payments & orders              |
+| Inventory search                    | Analytics & reporting          |
+| Proximity-based inventory discovery | Device scan collection         |
+| Vendor-scoped inventory retrieval   | Authentication & authorization |
+
+---
+
+### 1.4 Definitions
+
+| Term           | Description                                           |
+| -------------- | ----------------------------------------------------- |
+| Inventory Item | A product or service offered by a vendor              |
+| Vendor         | A business entity owning inventory                    |
+| Proximity      | Physical closeness inferred from detected Wi-Fi SSIDs |
+| Bulk Operation | An API request affecting multiple inventory items     |
+
+---
+
+## 2. System Overview
+
+### 2.1 Inventory Architecture Context
+
+| Component           | Responsibility                           |
+| ------------------- | ---------------------------------------- |
+| Client (Web/Mobile) | Requests inventory data                  |
+| Inventory API       | Inventory CRUD, search, proximity logic  |
+| MongoDB             | Vendor documents with embedded inventory |
+| DeviceScan Service  | Supplies proximity data (read-only)      |
+
+---
+
+### 2.2 Inventory Business Flow (Proximity)
+
+| Step | Description                           |
+| ---- | ------------------------------------- |
+| 1    | Device performs Wi-Fi scan            |
+| 2    | Latest scan stored in `DeviceScan`    |
+| 3    | Client requests `/inventory`          |
+| 4    | Device identity resolved from headers |
+| 5    | SSIDs matched against vendor SSIDs    |
+| 6    | Vendors with inventories returned     |
+
+---
+
+## 3. Inventory Data Model Requirements
+
+### 3.1 Inventory Item Schema (Embedded)
+
+| Field              | Type     | Required | Description                 |
+| ------------------ | -------- | -------- | --------------------------- |
+| item_id            | string   | Yes      | Unique inventory identifier |
+| name               | string   | Yes      | Item display name           |
+| category           | string   | No       | Item category               |
+| tags               | string[] | No       | Searchable keywords         |
+| price              | number   | No       | Item price                  |
+| quantity_available | number   | No       | Available stock count       |
+
+---
+
+### 3.2 Inventory Storage Model
+
+| Aspect          | Design Choice                     |
+| --------------- | --------------------------------- |
+| Storage         | Embedded inside Vendor document   |
+| Cardinality     | One vendor → many inventory items |
+| Lookup method   | Positional `$` operator           |
+| Deletion method | `$pull` on inventory array        |
+
+---
+
+## 4. Proximity Resolution (Inventory Context)
+
+### 4.1 Device Identification Priority
+
+| Priority | Source                |
+| -------- | --------------------- |
+| 1        | `x-device-sig` header |
+| 2        | `public_ip` header    |
+| 3        | `x-ws-token` header   |
+| 4        | Socket remote address |
+
+---
+
+### 4.2 Inventory Proximity Matching Rule
+
+| Rule               | Description                            |
+| ------------------ | -------------------------------------- |
+| Matching condition | Vendor SSID ∩ detected Wi-Fi SSIDs ≠ ∅ |
+| Data source        | Latest `DeviceScan` per device         |
+| Result             | Vendor inventory considered nearby     |
+
+---
+
+## 5. Functional Requirements (Inventory APIs)
+
+---
+
+### 5.1 Proximity Inventory Discovery
+
+| Attribute | Value                              |
+| --------- | ---------------------------------- |
+| Endpoint  | `GET /inventory`                   |
+| Purpose   | Retrieve nearby vendor inventories |
+| Input     | Device-identifying headers         |
+| Output    | List of vendor objects             |
+
+**Responses**
+
+| Code | Condition                    |
+| ---- | ---------------------------- |
+| 200  | Vendors with inventory found |
+| 404  | No proximity data available  |
+| 500  | Internal server error        |
+
+---
+
+### 5.2 Inventory Item Lookup
+
+| Attribute | Value                     |
+| --------- | ------------------------- |
+| Endpoint  | `GET /inventory/:itemId`  |
+| Purpose   | Retrieve item with vendor |
+| Input     | `itemId`                  |
+| Output    | Vendor info + item        |
+
+---
+
+### 5.3 Inventory Search
+
+| Attribute    | Value                     |
+| ------------ | ------------------------- |
+| Endpoint     | `GET /search`             |
+| Query Param  | `query`                   |
+| Search Scope | Vendor + inventory fields |
+| Matching     | Case-insensitive regex    |
+
+**Searchable Fields**
+
+| Entity    | Fields               |
+| --------- | -------------------- |
+| Vendor    | name, address        |
+| Inventory | name, category, tags |
+
+---
+
+### 5.4 Inventory Retrieval by Vendor
+
+| Attribute | Value                             |
+| --------- | --------------------------------- |
+| Endpoint  | `GET /vendor/:vendorId/inventory` |
+| Purpose   | Retrieve inventory for a vendor   |
+| Output    | Inventory array only              |
+
+---
+
+## 6. Inventory Management Operations
+
+---
+
+### 6.1 Single Inventory Item Operations
+
+| Action | Method | Endpoint                      |
+| -----: | ------ | ----------------------------- |
+|    Add | POST   | `/vendor/:vendorId/inventory` |
+| Update | PUT    | `/inventory/:itemId`          |
+| Delete | DELETE | `/inventory/:itemId`          |
+
+**Update Rules**
+
+| Rule           | Description                       |
+| -------------- | --------------------------------- |
+| Partial update | Only supplied fields updated      |
+| Targeting      | First matched `inventory.item_id` |
+
+---
+
+### 6.2 Bulk Inventory Operations
+
+| Action      | Method | Endpoint                           |
+| ----------- | ------ | ---------------------------------- |
+| Bulk add    | POST   | `/vendor/:vendorId/inventory/bulk` |
+| Bulk update | PUT    | `/inventory/:vendorId/bulk`        |
+| Bulk delete | DELETE | `/inventory`                       |
+
+**Bulk Behavior Guarantees**
+
+| Guarantee       | Description                          |
+| --------------- | ------------------------------------ |
+| Execution       | Best-effort                          |
+| Partial success | Allowed                              |
+| Isolation       | Per-item atomic updates              |
+| Feedback        | Per-item match & modification counts |
+
+---
+
+## 7. Error Handling
+
+| HTTP Code | Meaning                     |
+| --------- | --------------------------- |
+| 400       | Invalid input               |
+| 404       | Inventory or vendor missing |
+| 500       | Internal server error       |
+
+---
+
+## 8. Non-Functional Requirements
+
+### 8.1 Performance
+
+| Metric           | Requirement |
+| ---------------- | ----------- |
+| Typical response | < 500 ms    |
+| Bulk update size | ≥ 100 items |
+
+---
+
+### 8.2 Scalability
+
+| Aspect           | Requirement                                          |
+| ---------------- | ---------------------------------------------------- |
+| API              | Stateless                                            |
+| Scaling          | Horizontal                                           |
+| Required Indexes | `inventory.item_id`, `vendor_info.vendor_id`, `ssid` |
+
+---
+
+### 8.3 Reliability & Data Integrity
+
+| Requirement | Description                                 |
+| ----------- | ------------------------------------------- |
+| Atomicity   | Per-item inventory update                   |
+| Consistency | Inventory updates do not overwrite siblings |
+
+---
+
+### 8.4 Security Assumptions
+
+| Area           | Assumption                          |
+| -------------- | ----------------------------------- |
+| Authentication | Handled upstream                    |
+| Authorization  | Vendor ownership validated upstream |
+| Validation     | Required for all inventory inputs   |
+
+---
+
+## 9. Known Limitations
+
+| Limitation         | Impact                    |
+| ------------------ | ------------------------- |
+| Embedded inventory | Document size growth risk |
+| Regex search       | Not index-optimized       |
+| No pagination      | Large payload responses   |
+| No inventory locks | Concurrent edits possible |
+
+---
+
+## 10. Future Enhancements
+
+| Feature              | Description                    |
+| -------------------- | ------------------------------ |
+| Pagination           | Inventory & search results     |
+| Soft deletes         | Inventory lifecycle management |
+| Stock thresholds     | Low-stock alerts               |
+| Inventory versioning | Audit & rollback support       |
+
+---
+
+## 11. Reading Guide
+
+| Role              | Sections  |
+| ----------------- | --------- |
+| Stakeholders      | 1–4, 8–10 |
+| Backend Engineers | 3–10      |

package/docs/openapi.yaml

@@ -0,0 +1,344 @@
+openapi: 3.0.3
+info:
+  title: Proximity Inventory Backend API
+  description: |
+    Inventory domain APIs for the Proximity platform.
+    Supports proximity-based discovery, inventory search,
+    and single/bulk inventory management.
+  version: 1.0.0
+
+servers:
+  - url: https://www.proximityapp.ai
+    description: Production
+  - url: http://localhost:5000
+    description: Local development
+
+tags:
+  - name: Inventory
+    description: Inventory discovery and management
+  - name: Search
+    description: Text-based inventory search
+  - name: Proximity
+    description: Proximity-based inventory discovery
+
+paths:
+
+  /inventory:
+    get:
+      tags: [Proximity, Inventory]
+      summary: Get nearby vendor inventories
+      description: |
+        Returns vendors whose SSIDs match the latest
+        DeviceScan associated with the requesting device.
+      parameters:
+        - name: x-device-sig
+          in: header
+          schema: { type: string }
+        - name: public_ip
+          in: header
+          schema: { type: string }
+        - name: x-ws-token
+          in: header
+          schema: { type: string }
+      responses:
+        "200":
+          description: Vendors found
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Vendor"
+        "404":
+          description: No proximity data found
+        "500":
+          description: Internal server error
+
+    delete:
+      tags: [Inventory]
+      summary: Bulk delete inventory items
+      description: Deletes multiple inventory items across vendors.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [itemIds]
+              properties:
+                itemIds:
+                  type: array
+                  items:
+                    type: string
+      responses:
+        "200":
+          description: Inventory items deleted
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  deletedCount:
+                    type: number
+        "400":
+          description: Invalid request
+        "500":
+          description: Internal server error
+
+  /inventory/{itemId}:
+    get:
+      tags: [Inventory]
+      summary: Get inventory item by ID
+      parameters:
+        - name: itemId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        "200":
+          description: Inventory item found
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  vendor:
+                    $ref: "#/components/schemas/VendorInfo"
+                  item:
+                    $ref: "#/components/schemas/InventoryItem"
+        "404":
+          description: Inventory item not found
+        "500":
+          description: Internal server error
+
+    put:
+      tags: [Inventory]
+      summary: Update inventory item
+      parameters:
+        - name: itemId
+          in: path
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/InventoryItemUpdate"
+      responses:
+        "200":
+          description: Inventory item updated
+        "404":
+          description: Inventory item not found
+        "500":
+          description: Internal server error
+
+    delete:
+      tags: [Inventory]
+      summary: Delete inventory item
+      parameters:
+        - name: itemId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        "200":
+          description: Inventory item deleted
+        "404":
+          description: Inventory item not found
+        "500":
+          description: Internal server error
+
+  /inventory/{vendorId}/bulk:
+    put:
+      tags: [Inventory]
+      summary: Bulk update inventory items for a vendor
+      parameters:
+        - name: vendorId
+          in: path
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                allOf:
+                  - $ref: "#/components/schemas/InventoryItemUpdate"
+                  - type: object
+                    required: [item_id]
+                    properties:
+                      item_id:
+                        type: string
+      responses:
+        "200":
+          description: Bulk update completed
+        "400":
+          description: Invalid request
+        "404":
+          description: Vendor not found
+        "500":
+          description: Internal server error
+
+  /vendor/{vendorId}/inventory:
+    get:
+      tags: [Inventory]
+      summary: Get inventory for a vendor
+      parameters:
+        - name: vendorId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        "200":
+          description: Inventory list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/InventoryItem"
+        "404":
+          description: Vendor not found
+        "500":
+          description: Internal server error
+
+    post:
+      tags: [Inventory]
+      summary: Add inventory item to vendor
+      parameters:
+        - name: vendorId
+          in: path
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/InventoryItem"
+      responses:
+        "200":
+          description: Inventory item added
+        "404":
+          description: Vendor not found
+        "500":
+          description: Internal server error
+
+  /vendor/{vendorId}/inventory/bulk:
+    post:
+      tags: [Inventory]
+      summary: Bulk add inventory items to vendor
+      parameters:
+        - name: vendorId
+          in: path
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [items]
+              properties:
+                items:
+                  type: array
+                  items:
+                    $ref: "#/components/schemas/InventoryItem"
+      responses:
+        "200":
+          description: Inventory items added
+        "400":
+          description: Invalid request
+        "404":
+          description: Vendor not found
+        "500":
+          description: Internal server error
+
+  /search:
+    get:
+      tags: [Search]
+      summary: Search vendors and inventory
+      parameters:
+        - name: query
+          in: query
+          required: true
+          schema: { type: string }
+      responses:
+        "200":
+          description: Search results
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  query:
+                    type: string
+                  results:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        vendor_id:
+                          type: string
+                        vendor_name:
+                          type: string
+                        address:
+                          type: string
+                        inventory:
+                          type: array
+                          items:
+                            $ref: "#/components/schemas/InventoryItem"
+        "400":
+          description: Query missing
+        "500":
+          description: Internal server error
+
+components:
+  schemas:
+
+    Vendor:
+      type: object
+      properties:
+        vendor_info:
+          $ref: "#/components/schemas/VendorInfo"
+        inventory:
+          type: array
+          items:
+            $ref: "#/components/schemas/InventoryItem"
+
+    VendorInfo:
+      type: object
+      properties:
+        vendor_id:
+          type: string
+        name:
+          type: string
+        address:
+          type: string
+
+    InventoryItem:
+      type: object
+      required: [item_id, name]
+      properties:
+        item_id:
+          type: string
+        name:
+          type: string
+        category:
+          type: string
+        tags:
+          type: array
+          items:
+            type: string
+        price:
+          type: number
+        quantity_available:
+          type: number
+
+    InventoryItemUpdate:
+      type: object
+      additionalProperties: true

package/index.js

@@ -0,0 +1,537 @@
+import express from "express";
+/*import { DeviceScan } from "../models/DeviceScan.js";
+import { Vendor } from "../models/Vendor.js";
+
+const router = express.Router();
+router.proximityCache = {};
+/**
+ * Browser client calls this endpoint.
+ * Server finds last scan from same IP and returns matching vendor inventories.
+ */
+/*
+// 🧠 Fallback Matching Logic
+function findProximityKey(req) {
+  const ip = req.headers["public_ip"];
+  const deviceSig = req.headers["x-device-sig"];
+  const token = req.headers["x-ws-token"];
+  console.log("Device: ", deviceSig);
+  if (deviceSig) return deviceSig;
+  if (ip) return ip;
+  if (token) return token;
+  return null;
+}
+
+
+
+
+
+
+router.get("/inventory/:itemId", async (req, res) => {
+  try {
+    const itemId = req.params.itemId;
+
+    // Find the vendor that contains the inventory item
+    const vendor = await Vendor.findOne(
+      { "inventory.item_id": itemId },
+      { "inventory.$": 1, vendor_info: 1 } // project only the matching inventory item and vendor_info
+    ).lean();
+
+    if (!vendor || !vendor.inventory || vendor.inventory.length === 0) {
+      return res.status(404).json({ error: "Inventory item not found" });
+    }
+
+    res.json({
+      vendor: vendor.vendor_info,
+      item: vendor.inventory[0]
+    });
+  } catch (error) {
+    console.error(error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+
+
+
+
+
+router.get("/search", async (req, res) => {
+  try {
+    const { query } = req.query;
+
+    if (!query || query.trim() === "") {
+      return res.status(400).json({ error: "Query parameter is required" });
+    }
+
+    const regex = new RegExp(query, "i"); // case-insensitive fuzzy match
+
+    // Search inventory items
+    const vendors = await Vendor.find({
+      $or: [
+        { "vendor_info.name": regex },
+        { "vendor_info.address": regex },
+        { "inventory.name": regex },
+        { "inventory.category": regex },
+        { "inventory.tags": regex }
+      ]
+    }).lean();
+
+    const results = vendors.map(vendor => {
+      // Filter inventory items in vendor that match the query
+      const matchingItems = vendor.inventory.filter(item => 
+        regex.test(item.name) ||
+        regex.test(item.category) ||
+        item.tags.some(tag => regex.test(tag))
+      );
+
+      return {
+        vendor_id: vendor.vendor_info.vendor_id,
+        vendor_name: vendor.vendor_info.name,
+        address: vendor.vendor_info.address,
+        inventory: matchingItems
+      };
+    }).filter(vendor => vendor.inventory.length > 0 || regex.test(vendor.vendor_name) || regex.test(vendor.address));
+
+    res.json({
+      query,
+      results
+    });
+  } catch (error) {
+    console.error(error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+
+
+
+
+
+router.get("/inventory", async (req, res) => {
+  const deviceId = findProximityKey(req)|| req.socket.remoteAddress;
+
+  try {
+    const lastScan = await DeviceScan.findOne({ device_id: deviceId })
+      .sort({ timestamp: -1 })
+      .lean();
+    if (!lastScan) {
+      return res.status(404).json({ message: "No recent proximity data found for this IP" });
+    }
+    const ssids = lastScan?.detected_wifi.map(w => w.ssid);
+    console.log(ssids)
+    const vendors = await Vendor.find({ ssid: { $in: ssids } }).lean();
+    console.log(vendors);
+    res.json(vendors);
+  } catch (error) {
+    console.error(error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+
+
+
+
+// =========================
+// Get vendor by phoneNumber
+// =========================
+router.get("/vendor", async (req, res) => {
+  try {
+    const { phoneNumber } = req.query;
+    console.log(phoneNumber);
+    if (!phoneNumber) {
+      return res
+        .status(400)
+        .json({ error: "phoneNumber query parameter is required" });
+    }
+
+    // Find vendor using vendor_info.phoneNumber
+    const vendor = await Vendor.findOne({ "phoneNumber": phoneNumber })
+      .lean();
+
+    if (!vendor) {
+      return res.status(404).json({ error: "Vendor not found" });
+    }
+
+    res.json(vendor);
+
+  } catch (error) {
+    console.error("Error fetching vendor by phoneNumber:", error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+
+
+
+
+
+
+// Get inventory for a specific vendor
+router.get("/vendor/:vendorId/inventory", async (req, res) => {
+  try {
+    const vendorId = req.params.vendorId;
+    // Find the vendor by vendor_info.vendor_id
+    const vendor = await Vendor.findOne({ "vendor_info.vendor_id": vendorId })
+      .select("inventory") // only return inventory and vendor_info
+      .lean();
+
+    if (!vendor) {
+      return res.status(404).json({ error: "Vendor not found" });
+    }
+
+    res.json(vendor.inventory);
+  } catch (error) {
+    console.error(error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+
+
+
+
+
+
+
+// STORE MANAGEMENT STARTS HERE 
+router.get("/vendor/:vendorId", async (req, res) => {
+  try {
+    const vendorId = req.params.vendorId;
+    // vendor_id is inside vendor_info
+    const vendor = await Vendor.findOne({ "vendor_info.vendor_id": vendorId }).lean();
+
+    if (!vendor) {
+      return res.status(404).json({ error: "Vendor not found" });
+    }
+
+    res.json(vendor);
+  } catch (error) {
+    console.error(error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+
+
+
+
+// POST /vendor
+// body: { vendor_id, name, address, contact, gps_location, opening_hours, inventory }
+router.post("/vendor", async (req, res) => {
+  try {
+    const vendorData = req.body;
+
+    // Check if vendor already exists
+    const existing = await Vendor.findOne({ vendor_id: vendorData.vendor_id });
+    if (existing) {
+      return res.status(400).json({ error: "Vendor with this ID already exists" });
+    }
+
+    const newVendor = await Vendor.create(vendorData);
+    res.status(201).json({
+      message: "Vendor created successfully",
+      vendor: newVendor,
+    });
+  } catch (error) {
+    console.error(error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+
+
+
+
+
+// body: fields to update: { name, address, contact, gps_location, opening_hours, inventory }
+// PUT /vendor/:vendorId
+router.put("/vendor/:vendorId", async (req, res) => {
+  try {
+    const { vendorId } = req.params;
+    const updateData = req.body;
+
+    // Check if a vendor with this vendor_id exists
+    const existingVendor = await Vendor.findOne({ "vendor_info.vendor_id": vendorId });
+    if (!existingVendor) {
+      return res.status(404).json({ error: "Vendor not found" });
+    }
+
+    // Flatten nested updateData to update specific fields (so we don’t overwrite everything)
+    const setFields = {};
+    for (const [key, value] of Object.entries(updateData)) {
+      setFields[`vendor_info.${key}`] = value;
+    }
+
+    // Update vendor info
+    const updatedVendor = await Vendor.findOneAndUpdate(
+      { "vendor_info.vendor_id": vendorId },
+      { $set: setFields },
+      { new: true }
+    ).lean();
+
+    res.json({
+      message: "Vendor updated successfully",
+      vendor: updatedVendor,
+    });
+  } catch (error) {
+    console.error("Error updating vendor:", error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+
+
+
+
+
+// DELETE /vendor/:vendorId
+router.delete("/vendor/:vendorId", async (req, res) => {
+  try {
+    const { vendorId } = req.params;
+
+    const deletedVendor = await Vendor.findOneAndDelete({ vendor_id: vendorId }).lean();
+
+    if (!deletedVendor) {
+      return res.status(404).json({ error: "Vendor not found" });
+    }
+
+    res.json({
+      message: "Vendor deleted successfully",
+      vendor: deletedVendor,
+    });
+  } catch (error) {
+    console.error(error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+
+
+
+
+
+//INVENTORY STARTS HERE
+
+
+
+// Add a single inventory item to a vendor
+router.post("/vendor/:vendorId/inventory", async (req, res) => {
+  try {
+    const vendorId = req.params.vendorId;
+    const newItem = req.body; // e.g., { item_id, name, category, price, ... }
+
+    const updatedVendor = await Vendor.findOneAndUpdate(
+      { vendor_id: vendorId },
+      { $push: { inventory: newItem } },
+      { new: true, projection: { inventory: 1, vendor_info: 1 } }
+    ).lean();
+
+    if (!updatedVendor) {
+      return res.status(404).json({ error: "Vendor not found" });
+    }
+
+    res.json({
+      message: "Inventory item added successfully",
+      vendor: updatedVendor.vendor_info,
+      item: newItem,
+    });
+  } catch (error) {
+    console.error(error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+
+
+
+
+
+
+
+// Add multiple inventory items to a vendor
+router.post("/vendor/:vendorId/inventory/bulk", async (req, res) => {
+  try {
+    const vendorId = req.params.vendorId;
+    const newItems = req.body.items; // e.g., [{ item_id, name, ... }, {...}]
+
+    if (!Array.isArray(newItems) || newItems.length === 0) {
+      return res.status(400).json({ error: "Items array is required" });
+    }
+
+    const updatedVendor = await Vendor.findOneAndUpdate(
+      { vendor_id: vendorId },
+      { $push: { inventory: { $each: newItems } } },
+      { new: true, projection: { inventory: 1, vendor_info: 1 } }
+    ).lean();
+
+    if (!updatedVendor) {
+      return res.status(404).json({ error: "Vendor not found" });
+    }
+
+    res.json({
+      message: `${newItems.length} inventory items added successfully`,
+      vendor: updatedVendor.vendor_info,
+      items: newItems,
+    });
+  } catch (error) {
+    console.error(error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+
+
+
+
+
+
+router.put("/inventory/:itemId", async (req, res) => {
+  try {
+    const itemId = req.params.itemId;
+    const updateData = req.body; // e.g., { price: 300, quantity_available: 50 }
+
+    // Find the vendor containing the item and update the matching inventory element
+    const result = await Vendor.findOneAndUpdate(
+      { "inventory.item_id": itemId },
+      { $set: Object.fromEntries(
+          Object.entries(updateData).map(([key, value]) => [`inventory.$.${key}`, value])
+        )
+      },
+      { new: true, projection: { "inventory.$": 1, vendor_info: 1 } } // return updated item
+    ).lean();
+
+    if (!result || !result.inventory || result.inventory.length === 0) {
+      return res.status(404).json({ error: "Inventory item not found" });
+    }
+
+    res.json({
+      message: "Inventory item updated successfully",
+      vendor: result.vendor_info,
+      item: result.inventory[0],
+    });
+  } catch (error) {
+    console.error(error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+
+
+
+
+
+
+
+router.put("/inventory/:vendorId/bulk", async (req, res) => {
+  try {
+    const { vendorId } = req.params;
+    const itemsToUpdate = req.body;
+
+    if (!Array.isArray(itemsToUpdate) || itemsToUpdate.length === 0) {
+      return res.status(400).json({ error: "Items array is required" });
+    }
+
+    // Validate the vendor first
+    const vendor = await Vendor.findOne({ "vendor_info.vendor_id": vendorId });
+    if (!vendor) {
+      return res.status(404).json({ error: `Vendor ${vendorId} not found` });
+    }
+
+    // Perform updates in parallel
+    const updateResults = await Promise.all(
+      itemsToUpdate.map(async (item) => {
+        const { item_id, ...updates } = item;
+        const updateQuery = {};
+
+        // Dynamically build the update fields
+        for (const [key, value] of Object.entries(updates)) {
+          updateQuery[`inventory.$.${key}`] = value;
+        }
+
+        const result = await Vendor.updateOne(
+          { "vendor_info.vendor_id": vendorId, "inventory.item_id": item_id },
+          { $set: updateQuery }
+        );
+
+        return { item_id, matched: result.matchedCount, modified: result.modifiedCount };
+      })
+    );
+
+    // Fetch the fresh vendor document after updates
+    const updatedVendor = await Vendor.findOne({ "vendor_info.vendor_id": vendorId }).lean();
+
+
+    console.log(updateResults)
+
+    res.json({
+      message: `${updateResults.filter(r => r.modified > 0).length} of ${itemsToUpdate.length} items updated successfully`,
+      updateResults,
+      vendor: updatedVendor?.vendor_info,
+      inventory: updatedVendor?.inventory,
+    });
+
+  } catch (error) {
+    console.error("Bulk update error:", error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+
+
+
+
+
+
+// DELETE /inventory/:itemId
+router.delete("/inventory/:itemId", async (req, res) => {
+  try {
+    const { itemId } = req.params;
+
+    const result = await Vendor.findOneAndUpdate(
+      { "inventory.item_id": itemId },
+      { $pull: { inventory: { item_id: itemId } } },
+      { new: true, projection: { vendor_info: 1 } }
+    ).lean();
+
+    if (!result) {
+      return res.status(404).json({ error: "Inventory item not found" });
+    }
+
+    res.json({
+      message: "Inventory item deleted successfully",
+      vendor: result.vendor_info,
+    });
+  } catch (error) {
+    console.error(error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+
+
+
+
+
+
+// DELETE /inventory
+// body: { itemIds: ["INV001", "INV002", ...] }
+router.delete("/inventory", async (req, res) => {
+  try {
+    const { itemIds } = req.body;
+
+    if (!Array.isArray(itemIds) || itemIds.length === 0) {
+      return res.status(400).json({ error: "itemIds array is required" });
+    }
+
+    const result = await Vendor.updateMany(
+      { "inventory.item_id": { $in: itemIds } },
+      { $pull: { inventory: { item_id: { $in: itemIds } } } }
+    );
+
+    res.json({
+      message: "Inventory items deleted successfully",
+      deletedCount: result.modifiedCount,
+    });
+  } catch (error) {
+    console.error(error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+
+
+
+*/
+
+const router = express.Router();
+router.proximityCache = {};
+
+export default router;
+
+

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@shyntech-proximity/inventories",
-  "version": "1.0.2",
-  "main": "src/index.js",
+  "version": "1.0.4",
+  "main": "index.js",
   "files": [
     "dist",
-    "src"
+    "src",
+    "index.js",
+    "models/",
+    "docs/",
+    "README.md"
   ],
   "scripts": {
     "build": "echo 'no build'",