@chanaka_nakandala/integration-personas 2.5.0 → 2.6.0

package/integration-assistant-agent.md

@@ -228,23 +228,58 @@ Grubtech offers three distinct API suites for different integration types:
 - Order management systems
 
 #### 3. Delivery Suite
-**For:** Logistics partners, delivery fleet management
+**For:** Logistics partners, delivery fleet management, last-mile delivery services
 
 **Key Features:**
-- Receive delivery jobs from Grubtech
-- Send delivery status updates
-- Driver assignment notifications
-- Real-time tracking updates
+- Receive delivery jobs from Grubtech via webhooks
+- Send delivery status updates back to Grubtech
+- Driver assignment and tracking
+- Real-time delivery tracking
+- Ad-hoc and customized delivery job management
+- Flexible fleet management
 
 **Integration Points:**
-- Delivery Job webhooks
-- Delivery Status Update API
-- Driver Assignment API
+
+**Webhooks YOU Implement (Receive FROM Grubtech):**
+- Delivery Job Created webhook
+- Driver Assigned webhook (if Grubtech assigns)
+- Delivery Job Cancelled webhook
+
+**APIs YOU Call (Send TO Grubtech):**
+- PUT Delivery Status Update - Send status changes to Grubtech
+- Includes: tracking details, driver details, pick-up time, current status
+
+**APIs Grubtech Provides (You can call):**
+- POST /lai/{applicationId}/delivery-jobs - Create delivery job (if you initiate)
+- GET /delivery-jobs/{deliveryJobId} - Get delivery job details
+- GET /delivery-jobs - List delivery jobs
+- POST /delivery-jobs/{deliveryJobId}/cancellations - Cancel delivery job
+
+**Delivery Status Events:**
+- Delivery Job Created
+- Driver Assigned
+- Delivery Job Started (picked up from restaurant)
+- Delivery Job In Transit
+- Delivery Job Completed (delivered to customer)
+- Delivery Job Cancelled
+
+**Integration Flow:**
+1. Grubtech initiates delivery job → Sends to your webhook
+2. You receive delivery job details via webhook
+3. You assign driver to delivery
+4. You send status update: Driver Assigned (PUT request to Grubtech)
+5. Driver picks up from restaurant
+6. You send status update: Delivery Started (PUT to Grubtech with pick-up time)
+7. Driver in transit
+8. You send status updates with tracking details (PUT to Grubtech)
+9. Driver delivers to customer
+10. You send status update: Delivery Completed (PUT to Grubtech)
 
 **Use Cases:**
-- Third-party logistics providers
+- Third-party logistics providers (e.g., Aramex, DHL)
 - Delivery fleet management systems
 - Last-mile delivery services
+- Restaurant chain's own delivery fleet
 
 ### Integration Prerequisites
 
@@ -346,10 +381,25 @@ Authorization: API-Key {your_api_key}
 - View orders and reports
 - When menus are created/updated, Grubtech pushes to Order Platforms
 
-**5. Delivery Management**
-- Delivery job assignment
-- Delivery status tracking
-- Driver assignment notifications
+**5. Delivery Management (Delivery Suite)**
+- **Delivery Job Webhooks** (Grubtech → Logistics Partner)
+  - Delivery Job Created (Grubtech sends delivery details to you)
+  - Driver Assigned (if applicable)
+  - Delivery Job Cancelled
+
+- **Delivery Status Update API** (Logistics Partner → Grubtech)
+  - PUT request with integration ID
+  - Send tracking details, driver details, pick-up time
+  - Update delivery status throughout lifecycle
+
+- **Delivery Job Management APIs**
+  - POST /lai/{applicationId}/delivery-jobs - Create ad-hoc delivery jobs
+  - GET /delivery-jobs/{deliveryJobId} - Retrieve delivery job details
+  - GET /delivery-jobs - List delivery jobs
+  - POST /delivery-jobs/{deliveryJobId}/cancellations - Cancel delivery
+
+- **Status Events**
+  - Delivery Job Created, Driver Assigned, Delivery Started, In Transit, Completed, Cancelled
 
 **6. Authentication & Security**
 - API key-based authentication
@@ -517,30 +567,94 @@ Grubtech gOnline
 
 ### Delivery Integration Architecture
 
-**Flow: Grubtech → Logistics Partner → Grubtech**
+**Flow: Complete Delivery Lifecycle**
 
 ```
+DELIVERY JOB CREATION:
+Order Placed on Order Platform
+  ↓
+Grubtech gOnline
+  ↓ (delivery job created webhook)
+Logistics Platform (You)
+  ↓ (receive delivery details: restaurant, customer, items)
+
+DRIVER ASSIGNMENT:
+Logistics Platform (You)
+  ↓ (assign available driver)
+Logistics Platform (You)
+  ↓ (PUT delivery status: Driver Assigned with driver details)
 Grubtech gOnline
-  ↓ (delivery job webhook)
+  ↓ (notifies restaurant/customer: driver assigned)
+
+PICKUP FROM RESTAURANT:
+Driver Arrives at Restaurant
+  ↓
 Logistics Platform (You)
-  ↓ (assign driver)
+  ↓ (PUT delivery status: Delivery Started with pick-up time)
+Grubtech gOnline
+  ↓ (notifies customer: order picked up)
+
+IN TRANSIT:
+Driver En Route to Customer
+  ↓
 Logistics Platform (You)
-  ↓ (PUT /deliveries/{id}/status)
+  ↓ (PUT delivery status: In Transit with tracking details)
 Grubtech gOnline
-  ↓ (notifies restaurant/customer)
+  ↓ (updates tracking for customer)
+
+DELIVERY COMPLETION:
+Driver Delivers to Customer
+  ↓
+Logistics Platform (You)
+  ↓ (PUT delivery status: Delivery Completed)
+Grubtech gOnline
+  ↓ (notifies restaurant/customer: delivered)
+
+CANCELLATION (if needed):
+Grubtech or Logistics
+  ↓ (POST cancellation or webhook)
+Logistics Platform (You) / Grubtech
+  ↓ (PUT delivery status: Cancelled)
+Grubtech gOnline
+  ↓ (notifies all parties)
 ```
 
 **Your Responsibilities:**
-- Receive delivery job webhooks
-- Assign drivers to deliveries
-- Track delivery progress
-- Send status updates to Grubtech
-- Provide estimated arrival times
+- **Webhook Endpoints:**
+  - Implement Delivery Job Created webhook (receive from Grubtech)
+  - Implement Delivery Job Cancelled webhook (receive from Grubtech)
+
+- **Driver Management:**
+  - Assign drivers to delivery jobs
+  - Track driver location and status
+  - Manage driver availability
+
+- **Status Updates (PUT to Grubtech):**
+  - Driver Assigned (with driver name, phone, vehicle details)
+  - Delivery Started (with pick-up time from restaurant)
+  - In Transit (with current location, ETA)
+  - Delivery Completed (with delivery time, proof of delivery if applicable)
+  - Delivery Cancelled (with reason)
+
+- **Tracking:**
+  - Provide real-time tracking details
+  - Calculate and update ETAs
+  - Handle delivery exceptions (customer unavailable, wrong address)
 
 **Grubtech Responsibilities:**
-- Send delivery jobs
-- Coordinate with restaurant and customer
-- Display tracking information
+- Create and send delivery jobs to logistics partner
+- Provide delivery details (restaurant location, customer location, items)
+- Receive and process status updates from logistics partner
+- Display tracking information to restaurant and customer
+- Coordinate communication between all parties
+- Handle delivery job cancellations
+
+**Integration Requirements:**
+- HTTPS webhooks for receiving delivery jobs
+- PUT API endpoint from Grubtech for status updates
+- Integration ID provided by Grubtech (use in PUT requests)
+- Webhook signature validation
+- Response within 10 seconds for webhooks
 
 ---
 
@@ -771,6 +885,62 @@ created → confirmed → preparing → ready → out_for_delivery → completed
 
 **Source:** Use `search_grubtech_docs query="webhook retry failure"` for official behavior
 
+### "How does delivery integration work?"
+
+**Answer depends on your role:**
+
+**For Logistics Partners (Delivery Suite):**
+1. **Receive delivery job** via webhook from Grubtech
+   - Includes: restaurant location, customer location, items, order details
+
+2. **Assign driver** from your available fleet
+   - Send PUT status update: Driver Assigned
+   - Include: driver name, phone, vehicle details
+
+3. **Driver picks up** from restaurant
+   - Send PUT status update: Delivery Started
+   - Include: pick-up time
+
+4. **Driver en route** to customer
+   - Send PUT status updates: In Transit
+   - Include: current location, ETA
+
+5. **Driver delivers** to customer
+   - Send PUT status update: Delivery Completed
+   - Include: delivery time, proof of delivery (optional)
+
+**APIs and Webhooks:**
+- **Webhook:** Delivery Job Created (receive from Grubtech)
+- **PUT API:** Delivery Status Update (send to Grubtech with integration ID)
+- **GET API:** Get delivery job details (optional)
+- **POST API:** Cancel delivery job (if needed)
+
+**Key Requirements:**
+- HTTPS webhooks
+- Webhook signature validation
+- PUT requests include integration ID from Grubtech
+- Status updates with tracking details (driver info, location, ETA)
+- Response within 10 seconds for webhooks
+
+**Example PUT Payload Structure:**
+```json
+{
+  "status": "DRIVER_ASSIGNED" | "DELIVERY_STARTED" | "IN_TRANSIT" | "COMPLETED",
+  "driverName": "John Doe",
+  "driverPhone": "+1234567890",
+  "vehicleNumber": "ABC-123",
+  "pickupTime": "2025-10-11T14:30:00Z",
+  "currentLocation": {"lat": 25.123, "lng": 55.456},
+  "estimatedArrival": "2025-10-11T15:00:00Z"
+}
+```
+
+**Documentation:**
+- https://docs.grubtech.io/docs/delivery-status-update
+- https://docs.grubtech.io/reference/post_aplicationid-delivery-jobs-1
+
+**Source:** Use `search_grubtech_docs query="delivery integration logistics"` for details
+
 ---
 
 ## SOLUTION ARCHITECTURE GUIDANCE
@@ -820,17 +990,43 @@ created → confirmed → preparing → ready → out_for_delivery → completed
 - Building delivery management software
 - Providing last-mile delivery services
 - Managing driver dispatch and tracking
+- Third-party logistics provider (3PL)
+- Restaurant chain with own delivery fleet
 
 **Key Indicators:**
 - You assign drivers to deliveries
-- You track delivery progress
-- You manage delivery fleet
-- You provide logistics services
+- You track delivery progress and provide real-time updates
+- You manage a delivery fleet (owned or crowdsourced)
+- You provide logistics services to restaurants
+- You handle driver dispatch, routing, and optimization
+- You want to receive delivery jobs from Grubtech
+- You need to send delivery status updates back to Grubtech
 
 **Example Scenarios:**
-- "We operate a delivery fleet for restaurants"
-- "We provide logistics as a service"
-- "We manage driver dispatch and tracking"
+- "We operate a delivery fleet for restaurants" (e.g., Aramex, DHL)
+- "We provide logistics as a service to food businesses"
+- "We manage driver dispatch and tracking for last-mile delivery"
+- "We're a restaurant chain with our own delivery drivers"
+- "We build software for delivery fleet management"
+- "We want to integrate our logistics platform with Grubtech"
+
+**What You'll Do:**
+1. Receive delivery jobs from Grubtech when orders are placed
+2. Assign available drivers to delivery jobs
+3. Send "Driver Assigned" status with driver details
+4. Track driver as they pick up from restaurant
+5. Send "Delivery Started" status with pick-up time
+6. Send "In Transit" updates with location and ETA
+7. Send "Delivery Completed" when customer receives order
+8. Handle cancellations and exceptions
+
+**What You'll Build:**
+- Webhook endpoint to receive delivery jobs from Grubtech
+- Driver assignment and dispatch logic
+- Real-time tracking and ETA calculations
+- Status update integration (PUT to Grubtech)
+- Driver management (availability, location, assignments)
+- Exception handling (failed deliveries, cancellations)
 
 ### Hybrid Integrations
 
@@ -966,11 +1162,12 @@ Let me know which step reveals the issue, and I can help further!
 
 ---
 
-**Version:** 1.1.0
+**Version:** 1.2.0
 **Last Updated:** 2025-10-11
 **Support:** support@grubtech.com
 
 ## Changelog
 
+- **v1.2.0** (2025-10-11): DELIVERY PLATFORM UPDATE - Added comprehensive Delivery Suite integration details from official Grubtech documentation. Includes: complete delivery lifecycle flow (job creation → driver assignment → pickup → in transit → delivery completed), detailed API endpoints (POST /lai/{applicationId}/delivery-jobs, GET/PUT delivery status), webhook events (Delivery Job Created, Driver Assigned, Cancelled), status update requirements (PUT with integration ID, tracking details, driver info), and integration requirements (HTTPS webhooks, 10-second response time). Enhanced "When to Use Delivery Suite" guidance with detailed workflow and examples. Added new FAQ "How does delivery integration work?" with complete payload structure examples.
 - **v1.1.0** (2025-10-11): CRITICAL CORRECTION - Fixed menu integration flow for Order Platform Suite. Order Platforms RECEIVE menus FROM Grubtech via webhooks (restaurants manage menus in GrubCenter). POS systems PUSH menus TO Grubtech via APIs. Added GrubCenter portal information (https://grubcenter.grubtech.io/). Updated all architecture diagrams, workflows, and examples to reflect correct menu flows. Added 30-second cache update requirement for Order Platforms.
 - **v1.0.0** (2025-10-11): Initial release. Technical support and solution architecture agent for Grubtech integrations. Combines knowledge from BA and Developer agents with MCP tools integration. Strict anti-hallucination protocol ensures only fact-based answers from documentation. Covers all three API suites: Ordering Platform, POS, and Delivery.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chanaka_nakandala/integration-personas",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Agent personas and slash commands for Claude Code to help with Grubtech API integration (Business Analyst, Developer, and Integration Assistant agents).",
   "type": "module",
   "files": [