{"openapi":"3.0.0","info":{"title":"KNG Electronics — Enterprise REST API","version":"1.0.0","description":"High-performance global edge REST API for KNG Electronics platform (E-Commerce, Cloudflare D1 Database, R2 Cloud Media Storage, Real-time Inventory & KHQR Payments).","contact":{"name":"KNG Electronics Engineering Team","url":"https://kngpackingsolutions.com","email":"support@kngpackingsolutions.com"}},"servers":[{"url":"https://kng-api.nhem-chan-98.workers.dev","description":"Cloudflare Edge API (Global Online Cloud)"},{"url":"https://admin.kngpackingsolutions.com","description":"Production Admin Domain"},{"url":"https://kngpackingsolutions.com","description":"Production Storefront Domain"},{"url":"http://localhost:4000","description":"Local NestJS Backend Server"},{"url":"http://127.0.0.1:4000","description":"Local Loopback Server"}],"tags":[{"name":"System","description":"System health check and runtime telemetry"},{"name":"Products","description":"Product catalog, pricing, variants, and stock management"},{"name":"Categories","description":"Product hierarchy and category classification"},{"name":"Orders","description":"Order submission, billing, and checkout pipeline"},{"name":"Media Storage (R2)","description":"Cloudflare R2 edge media and photo assets"}],"paths":{"/api/health":{"get":{"tags":["System"],"summary":"Check API and Database Health Status","description":"Returns real-time engine telemetry, runtime binding status (D1 & R2), and server timestamp.","responses":{"200":{"description":"System healthy and operational","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"service":{"type":"string","example":"KNG Cloudflare Worker API"},"engine":{"type":"string","example":"V8 Edge Runtime"},"timestamp":{"type":"string","example":"2026-09-26T15:00:00.000Z"},"bindings":{"type":"object","properties":{"d1":{"type":"boolean","example":true},"r2":{"type":"boolean","example":true}}}}}}}}}}},"/api/products":{"get":{"tags":["Products"],"summary":"List Products with Filtering and Search","description":"Retrieves products from Cloudflare D1 with optional filtering by category slug or keyword search.","parameters":[{"name":"category","in":"query","description":"Filter by category ID, name, or slug","schema":{"type":"string","example":"ទូរស័ព្ទដៃ"}},{"name":"search","in":"query","description":"Keyword search in product title, description, or slug","schema":{"type":"string"}},{"name":"all","in":"query","description":"Set to true to retrieve both in-stock and out-of-stock items (Admin mode)","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"List of matching products","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"p-1"},"sku":{"type":"string","example":"IP16PM-256GB-BLK"},"name":{"type":"string","example":"iPhone 16 Pro Max"},"priceUsd":{"type":"number","example":1199},"stock":{"type":"integer","example":45},"category":{"type":"string","example":"ទូរស័ព្ទដៃ"},"imageUrl":{"type":"string","example":"https://images.unsplash.com/..."},"status":{"type":"string","example":"IN_STOCK"}}}}}}}}}}},"post":{"tags":["Products"],"summary":"Create or Batch Upsert Products","description":"Saves an array of products or a single product into the Cloudflare D1 database.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["name","priceUsd"],"properties":{"id":{"type":"string","example":"PROD-001"},"sku":{"type":"string","example":"IP16PM-BLK"},"name":{"type":"string","example":"iPhone 16 Pro Max"},"priceUsd":{"type":"number","example":1199},"stock":{"type":"integer","example":50},"category":{"type":"string","example":"ទូរស័ព្ទដៃ"},"imageUrl":{"type":"string","example":"https://images.unsplash.com/..."},"description":{"type":"string","example":"Official Apple flagship smartphone"}}}}}}},"responses":{"200":{"description":"Products saved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"count":{"type":"integer","example":1}}}}}}}}},"/api/products/{id}":{"put":{"tags":["Products"],"summary":"Update Product Stock, Category, or Information","description":"Updates specific attributes or inventory count for a product by ID or SKU in D1.","parameters":[{"name":"id","in":"path","required":true,"description":"Product unique ID or SKU","schema":{"type":"string","example":"p-1"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stock":{"type":"integer","example":25},"category":{"type":"string","example":"ទូរស័ព្ទដៃ"},"priceUsd":{"type":"number","example":1199}}}}}},"responses":{"200":{"description":"Product updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Product updated in D1"}}}}}}}},"delete":{"tags":["Products"],"summary":"Permanently Delete Product","description":"Deletes a product by ID or slug permanently from the Cloudflare D1 database.","parameters":[{"name":"id","in":"path","required":true,"description":"Product ID or SKU to permanently remove","schema":{"type":"string","example":"p-1"}}],"responses":{"200":{"description":"Product deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Product deleted from D1"},"id":{"type":"string","example":"p-1"}}}}}}}}},"/api/categories":{"get":{"tags":["Categories"],"summary":"List All Product Categories","description":"Retrieves all active product categories ordered by display sort order.","responses":{"200":{"description":"List of product categories","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cat_smartphones"},"name_km":{"type":"string","example":"ទូរស័ព្ទដៃ"},"name_en":{"type":"string","example":"Smartphones"},"slug":{"type":"string","example":"smartphones"}}}}}}}}}}},"post":{"tags":["Categories"],"summary":"Create or Update Category","description":"Creates a new category in Cloudflare D1.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nameKm","nameEn"],"properties":{"id":{"type":"string","example":"cat_tablets"},"nameKm":{"type":"string","example":"ថេបប្លេត និង iPad"},"nameEn":{"type":"string","example":"Tablets & iPad"},"slug":{"type":"string","example":"tablets"}}}}}},"responses":{"200":{"description":"Category saved successfully"}}}},"/api/orders":{"get":{"tags":["Orders"],"summary":"List Recent Orders (Admin)","description":"Retrieves recent customer orders, payment status, and order item details from D1.","responses":{"200":{"description":"Orders list"}}},"post":{"tags":["Orders"],"summary":"Create Order & Deduct Inventory","description":"Submits a new customer checkout order with atomic inventory deduction in Cloudflare D1.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customerName","customerPhone","items"],"properties":{"customerName":{"type":"string","example":"Chan IT"},"customerPhone":{"type":"string","example":"012 345 678"},"totalUsd":{"type":"number","example":1199},"paymentMethod":{"type":"string","example":"BAKONG_KHQR"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"p-1"},"name":{"type":"string","example":"iPhone 16 Pro Max"},"priceUsd":{"type":"number","example":1199},"quantity":{"type":"integer","example":1}}}}}}}}},"responses":{"200":{"description":"Order created successfully"}}}},"/api/images/upload":{"post":{"tags":["Media Storage (R2)"],"summary":"Upload Product Photo to Cloudflare R2","description":"Uploads an image file to Cloudflare R2 global storage bucket and returns an optimized CDN URL.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"Image file (JPEG, PNG, WebP)"}}}}}},"responses":{"200":{"description":"Image uploaded successfully with public URL","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"url":{"type":"string","example":"https://kng-api.nhem-chan-98.workers.dev/api/images/products/123.jpg"}}}}}}}}}}}