docs:Create a Comprehensive API Reference Guide for Inventory Sync #12

docs/api/API-Reference.md

@@ -0,0 +1,218 @@
+# API Reference Guide
+
+## 1\. Overview
+
+This API provides programmatic access to the Inventory Sync platform, allowing for user authentication and profile management. It is built using Laravel and follows RESTful principles.
+
+*   **Base URL:** `https://api.yourdomain.com/`
+
+*   **Format:** `application/json`
+
+*   **Primary Capability**: Asynchronous inventory state reconciliation.
+
+
+## 2\. Authentication
+
+The API currently supports session-based authentication and is transitioning toward token-based (JWT/Passport) integration.
+
+**Token Usage Example (JWT/Passport)**
+All protected requests must include the following header:
+
+```bash
+Authorization: Bearer {your_access_token}
+```
+
+*   **Middleware:** Routes protected by the `auth` middleware require a valid session or token.
+
+*   **Public Routes:** Registration and login endpoints are accessible via the `guest` middleware.
+
+
+## 3\. Endpoint Catalog
+
+### Authentication Endpoints
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| POST | /register | Create a new user account. |
+| POST | /login | Authenticate a user and start a session. |
+| POST | /logout | Terminate the current session. |
+
+### Settings & Profile Endpoints
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| GET | /settings/profile |Reads or shows the current user's profile information. |
+| PATCH | /settings/profile | Update the current user's profile information. |
+| DELETE | /settings/profile | Permanently delete the user's account. |
+| GET | /settings/password | Reads or shows the user's authentication password.|
+| PUT | /settings/password | Update the user's authentication password. |
+| GET | /setttings/appearance | Retrieve UI/UX display preference. |
+
+* * *
+
+## 4\. Request Logic & Examples
+
+### Login Request
+
+**Logic:** Based on `LoginRequest.php`, the system enforces strict validation and rate limiting.
+
+*   **Rate Limit:** 5 attempts per minute.
+
+*   **Parameters:**
+
+    *   `email` (string, required, valid email format).
+
+    *   `password` (string, required).
+
+
+**Example cURL:**
+
+```Bash
+// Sample Login Request using Axios
+axios.post('https://api.yourdomain.com/login', {
+    email: 'user@example.com',
+    password: 'securepassword'
+})
+.then(response => console.log(response.data))
+.catch(error => console.error(error.response.status));
+```
+### Profile Update Request
+
+**Logic:** Derived from `ProfileUpdateRequest.php`.
+
+*   **Parameters:**
+
+    *   `name` (string, required, max 255 chars).
+
+    *   `email` (string, required, unique to user table).
+
+
+* * *
+## 5\. Detailed Request & Response Examples
+
+### Login (`POST /login`)
+
+## 
+
+**Logic Source:** `LoginRequest.php` (Includes rate limiting of 5 attempts).
+
+**Request Body:**
+
+```JSON
+
+    {
+      "email": "dev@example.com",
+      "password": "secure_password_string"
+    }
+```
+**Response (200 OK):**
+
+```JSON
+
+    {
+      "token": "1|abc123def456...",
+      "status": "success"
+    }
+```
+
+### Inventory Sync (`POST /api/inventory/sync`)
+
+## 
+
+**Logic Source:** `queue.php` & `services.php`. This uses the `database` queue driver for background processing.
+
+**Request Body:**
+
+```JSON
+
+    {
+      "source": "shopify",
+      "options": {
+        "sync_images": true,
+        "ai_tagging": true
+      }
+    }
+```
+**Response (202 Accepted):**
+
+```JSON
+
+    {
+      "message": "Sync initiated.",
+      "task_id": "sync_job_99821",
+      "check_status_at": "/api/inventory/status?id=sync_job_99821"
+    }
+```
+
+
+## 6\. Error Handling
+
+The API returns standard HTTP status codes. Logic for these is found in the Request validation and Middleware layers.
+
+| Code | Meaning | Reason |
+| --- | --- | --- |
+| 401 | Unauthorized | Accessing a route protected by auth without credentials. |
+| 422 | Unprocessable Entity | Validation failed (e.g., missing email or incorrect format). |
+| 429 | Too Many Requests | Rate limit of 5 attempts exceeded. |
+
+## 7\. Inventory Management Endpoints
+
+### Sync Inventory
+
+**Endpoint:** `POST /api/inventory/sync`
+
+**Logic:** This endpoint triggers the AI-powered synchronization engine. Based on `config/queue.php`, this is an **asynchronous operation**. The API will return a "Task ID" while the background job processes the sync via the drivers defined in `config/services.php`.
+
+*   **Request Headers:** \* `Authorization: Bearer <token>`
+
+    *   `Content-Type: application/json`
+
+*   **Request Body:**
+
+    *   `source` (string, required): The marketplace slug (e.g., `amazon`, `shopify`).
+
+    *   `options` (array, optional): Filter criteria for specific SKUs.
+
+
+**Example Response (202 Accepted):**
+
+### Create Inventory Item
+
+**Endpoint:** `POST /api/inventory/items`
+
+**Logic:** Directly adds an item to the local database. The fields are derived from the standard schema indicated in `config/database.php`.
+
+*   **Parameters:**
+
+    *   `sku` (string, required): Unique identifier for the product.
+
+    *   `quantity` (integer, required): Current stock level.
+
+    *   `metadata` (json, optional): Additional AI-generated tags or product descriptions.
+
+
+* * *
+
+## 8\. Third-Party Integrations
+
+
+The API interacts with the following external services to facilitate syncing:
+
+*   **Postmark/Mail:** Used for sync completion notifications (via `config/mail.php`).
+
+*   **S3 Storage:** Used for storing inventory CSV exports or product images (via `config/filesystems.php`).
+
+*   **Slack:** Optional bot notifications for critical stock level alerts (via `config/services.php`).
+
+
+* * *
+
+## 9\. Rate Limiting & Performance
+
+# 
+
+To ensure stability, the following limits are enforced (derived from `LoginRequest.php` patterns):
+
+*   **Sync Frequency:** Limited to 1 request per 5 minutes per user to prevent queue congestion.
+
+*   **Batch Size:** Maximum of 500 items per single `POST` request.