Add Pathao Courier Integration with Admin UI for Bangladesh logistics

.env.example

@@ -16,3 +16,12 @@ NEXTAUTH_URL="http://localhost:3000"
 # Email Configuration
 EMAIL_FROM="noreply@example.com"
 RESEND_API_KEY="re_dummy_key_for_build"  # Build fails without this
+
+# Pathao Courier Integration (Optional - Per Store Configuration)
+# These are stored per-store in the database via Store model
+# Use admin panel to configure Pathao credentials for each store
+# PATHAO_CLIENT_ID="your_client_id"
+# PATHAO_CLIENT_SECRET="your_client_secret"
+# PATHAO_REFRESH_TOKEN="your_refresh_token"
+# PATHAO_STORE_ID="123"  # Pathao pickup store ID
+# PATHAO_MODE="sandbox"  # or "production"

PATHAO_CHECKOUT_FIX.md

@@ -0,0 +1,222 @@
+# Pathao Checkout Integration Fix
+
+## Problem Description
+
+The storefront checkout page was not collecting Pathao zone information (city_id, zone_id, area_id) during order creation. This caused the Pathao shipment creation API to fail with the error:
+
+> "Shipping address missing Pathao zone information. Please update the address with city, zone, and area IDs."
+
+## Root Cause
+
+The checkout form at [src/app/store/[slug]/checkout/page.tsx](src/app/store/[slug]/checkout/page.tsx) only collected standard address fields (address, city, state, postal code, country) but did not include:
+- Pathao City ID and Name
+- Pathao Zone ID and Name  
+- Pathao Area ID and Name
+
+Without these fields, when merchants tried to create a Pathao shipment from the admin panel, the API validation failed because the shipping address lacked the required Pathao-specific location identifiers.
+
+## Solution Implemented
+
+### 1. Added Pathao Address Fields to Form Schema
+
+Updated the `checkoutSchema` in `src/app/store/[slug]/checkout/page.tsx` to include optional Pathao fields:
+
+```typescript
+const checkoutSchema = z.object({
+  // ... existing fields ...
+
+  // Pathao delivery location (required for Bangladesh orders)
+  pathaoCityId: z.number().nullable().optional(),
+  pathaoCityName: z.string().optional(),
+  pathaoZoneId: z.number().nullable().optional(),
+  pathaoZoneName: z.string().optional(),
+  pathaoAreaId: z.number().nullable().optional(),
+  pathaoAreaName: z.string().optional(),
+
+  // ... rest of fields ...
+});
+```
+
+### 2. Integrated PathaoAddressSelector Component
+
+Added the `PathaoAddressSelector` component to the shipping address section of the checkout form:
+
+```tsx
+{/* Pathao Delivery Location (for Bangladesh orders) */}
+{storeData && (
+  <div className="mt-6">
+    <PathaoAddressSelector
+      organizationId={storeData.organizationId}
+      value={pathaoAddress}
+      onChange={setPathaoAddress}
+      required={false}
+    />
+    <p className="text-xs text-muted-foreground mt-2">
+      Select your Pathao delivery location for accurate shipping via Pathao courier service.
+      This is optional but recommended for Bangladesh deliveries.
+    </p>
+  </div>
+)}
+```
+
+This component provides:
+- **City Selector**: Dropdown to select Pathao city
+- **Zone Selector**: Dropdown to select zone within the city (enabled after city selection)
+- **Area Selector**: Dropdown to select specific area within the zone (enabled after zone selection)
+- **Real-time Data Fetching**: Cascading dropdowns that fetch zones for selected city and areas for selected zone
+- **Visual Feedback**: Loading states and selected location display
+
+### 3. Updated Order Creation Payload
+
+Modified the shipping address payload to include Pathao zone information:
+
+```typescript
+shippingAddress: {
+  address: data.shippingAddress,
+  city: data.shippingCity,
+  state: data.shippingState,
+  postalCode: data.shippingPostalCode,
+  country: data.shippingCountry,
+  // Include Pathao zone information if selected
+  pathao_city_id: pathaoAddress.cityId,
+  pathao_city_name: pathaoAddress.cityName,
+  pathao_zone_id: pathaoAddress.zoneId,
+  pathao_zone_name: pathaoAddress.zoneName,
+  pathao_area_id: pathaoAddress.areaId,
+  pathao_area_name: pathaoAddress.areaName,
+},
+```
+
+### 4. Added Store Data Fetching
+
+Added logic to fetch the store's `organizationId` which is required by the PathaoAddressSelector:
+
+```typescript
+const [storeData, setStoreData] = useState<{ organizationId: string } | null>(null);
+
+useEffect(() => {
+  const fetchStoreData = async () => {
+    try {
+      const response = await fetch(`/api/store/${storeSlug}`);
+      if (response.ok) {
+        const data = await response.json();
+        setStoreData({ organizationId: data.store.organizationId });
+      }
+    } catch (error) {
+      console.error('Failed to fetch store data:', error);
+    }
+  };
+  fetchStoreData();
+}, [storeSlug]);
+```
+
+## How It Works
+
+### Customer Flow
+
+1. **Customer Enters Standard Address**
+   - Customer fills in name, email, phone
+   - Enters shipping address, city, state, postal code, country
+
+2. **Customer Selects Pathao Location (Optional but Recommended)**
+   - Selects city from dropdown (e.g., "Dhaka")
+   - Selects zone from dropdown (e.g., "Mirpur")
+   - Selects area from dropdown (e.g., "Mirpur-1")
+   - System displays selected location: "📍 Mirpur-1, Mirpur, Dhaka"
+
+3. **Order Creation**
+   - Order is created with both standard address and Pathao zone information
+   - Address is saved as JSON in the database
+
+4. **Merchant Creates Shipment**
+   - Merchant opens order in admin panel
+   - Clicks "Create Pathao Shipment"
+   - System validates that Pathao zone information exists
+   - Shipment is successfully created via Pathao API
+
+### Technical Flow
+
+```
+Customer Checkout
+    ↓
+PathaoAddressSelector Component
+    ↓
+Fetch Cities (/api/shipping/pathao/cities)
+    ↓
+Select City → Fetch Zones (/api/shipping/pathao/zones/[cityId])
+    ↓
+Select Zone → Fetch Areas (/api/shipping/pathao/areas/[zoneId])
+    ↓
+Select Area → Update State
+    ↓
+Order Creation with Pathao Data
+    ↓
+Order Stored in DB with JSON Address
+    ↓
+Merchant Creates Shipment → Validates Pathao Fields → Success
+```
+
+## Benefits
+
+1. **Seamless Integration**: Customers can select their Pathao delivery location directly during checkout
+2. **Backward Compatible**: Pathao fields are optional, so existing checkouts still work
+3. **Prevents Shipment Creation Errors**: Orders now contain all required Pathao data
+4. **Better UX**: Cascading dropdowns guide customers through location selection
+5. **Accurate Delivery**: Precise location data ensures correct Pathao courier assignment
+
+## Testing Checklist
+
+- [x] Checkout form loads without errors
+- [x] PathaoAddressSelector displays cities
+- [x] Selecting city loads zones
+- [x] Selecting zone loads areas
+- [x] Selected location is displayed
+- [x] Order can be created without Pathao data (backward compatible)
+- [x] Order can be created with Pathao data
+- [x] Pathao shipment creation succeeds with valid zone data
+- [x] Pathao shipment creation fails gracefully without zone data
+
+## Files Modified
+
+1. `src/app/store/[slug]/checkout/page.tsx`
+   - Added Pathao fields to schema
+   - Integrated PathaoAddressSelector component
+   - Added store data fetching
+   - Updated order creation payload
+
+## Files Already Implemented (No Changes Needed)
+
+1. `src/components/shipping/pathao-address-selector.tsx`
+   - Reusable component for Pathao location selection
+
+2. `src/app/api/shipping/pathao/cities/route.ts`
+   - API endpoint for fetching Pathao cities
+
+3. `src/app/api/shipping/pathao/zones/[cityId]/route.ts`
+   - API endpoint for fetching zones by city
+
+4. `src/app/api/shipping/pathao/areas/[zoneId]/route.ts`
+   - API endpoint for fetching areas by zone
+
+5. `src/app/api/shipping/pathao/create/route.ts`
+   - Validates Pathao zone information before creating shipment
+
+## Future Enhancements
+
+1. **Required for Bangladesh**: Make Pathao fields required when shipping country is Bangladesh
+2. **Pre-fill from Profile**: Auto-fill Pathao location from customer's saved addresses
+3. **Delivery Time Estimates**: Show estimated delivery time based on selected area
+4. **Shipping Cost Calculator**: Calculate Pathao shipping costs during checkout
+5. **Store-level Settings**: Allow merchants to enable/disable Pathao integration per store
+
+## Related Documentation
+
+- [PATHAO_INTEGRATION_GUIDE.md](docs/PATHAO_INTEGRATION_GUIDE.md) - Complete Pathao integration guide
+- [PATHAO_TESTING_GUIDE.md](PATHAO_TESTING_GUIDE.md) - Testing instructions
+- [PATHAO_ADMIN_UI_GUIDE.md](docs/PATHAO_ADMIN_UI_GUIDE.md) - Admin panel usage
+
+---
+
+**Status**: ✅ Fixed and deployed
+**Date**: December 22, 2025
+**Implemented By**: GitHub Copilot