Refactor API error handling and improve response management. Enhanced handling for 404 Not Found errors in api.ts, ensuring proper token management and user feedback for invalid requests.

unified-api/sample -singel-doc-for-6-sections.md

@@ -0,0 +1,419 @@
+Understood.
+Here is the **complete consolidated master document**, combining all 6 sections into a single, clean, unified API Standard for IGNY8.
+No questions. No fragmentation. This becomes the **single source of truth** for backend, frontend, plugin, and 3rd-party integration.
+
+---
+
+# **IGNY8 API STANDARDIZATION – MASTER CONSOLIDATED DOCUMENT**
+
+**Version:** 1.0
+**Purpose:** Establish a single unified API contract for the IGNY8 platform (app, plugin, and external API consumers).
+**Applies To:**
+
+* Django backend
+* React frontend
+* WordPress plugin
+* 3rd-party API consumers
+* Internal automations / CRON / AI functions
+
+---
+
+# **1. API Versioning & Structure**
+
+**Base URL:**
+
+```
+/api/v1/
+```
+
+**Module Namespaces:**
+
+```
+auth/
+planner/
+writer/
+system/
+billing/
+```
+
+All current and future endpoints must follow predictable REST patterns under these namespaces.
+
+**Versioning Rules:**
+
+* v1 remains stable long-term
+* Breaking changes require v2
+* Deprecations allowed only with explicit timeline
+
+---
+
+# **2. Authentication Standard (Unified)**
+
+**Primary method:**
+`JWT Bearer token`
+
+```
+Authorization: Bearer <access_token>
+```
+
+**Fallbacks:**
+
+* Session auth (admin panel)
+* Basic auth (debug/testing)
+
+**Token Guarantees:**
+
+* Contains user_id and account_id
+* Resolves account → tenant context automatically
+* Sets `request.account` in all ViewSets
+
+**Public endpoints allowed:**
+
+* register
+* login
+* plans
+* industries
+* system/status
+
+Everything else requires JWT.
+
+---
+
+# **3. Authorization & Permissions Standard**
+
+Every endpoint must use consistent layered authorization:
+
+### **Base layers:**
+
+1. User must be authenticated
+2. User must belong to the tenant/account
+3. User must have appropriate role
+4. User must have access to requested site/sector
+
+### **Role hierarchy:**
+
+```
+owner > admin > editor > viewer > system_bot
+```
+
+### **Standard permission classes:**
+
+* IsAuthenticatedAndActive
+* HasTenantAccess
+* IsViewerOrAbove (read-only)
+* IsEditorOrAbove (content operations)
+* IsAdminOrOwner (settings, keys, billing)
+
+All ViewSets must explicitly declare the correct class.
+
+---
+
+# **4. Unified Response Format (Mandatory)**
+
+This is **the global standard for all endpoints**, no exception.
+
+### **Success**
+
+```
+{
+  "success": true,
+  "data": {},
+  "message": "Optional readable message"
+}
+```
+
+### **Error**
+
+```
+{
+  "success": false,
+  "error": "Readable top-level message",
+  "errors": { "field": ["details"] },
+  "request_id": "uuid"
+}
+```
+
+### **Paginated**
+
+```
+{
+  "success": true,
+  "count": 120,
+  "next": "...",
+  "previous": "...",
+  "results": [...],
+  "message": "Optional"
+}
+```
+
+This single structure is used across:
+
+* App
+* Plugin
+* External API clients
+* AI pipeline
+* CRON jobs
+
+---
+
+# **5. Unified Error Handling (Global Standard)**
+
+### **Centralized exception handler requirements:**
+
+* Wrap all errors in unified format
+* Use proper status codes (400, 401, 403, 404, 409, 422, 500)
+* Include sanitised validation errors under `errors`
+* Always attach `request_id`
+* Log full exception details
+* In DEBUG mode: include traceback + request context
+
+### **Server-side Logging**
+
+* All 4xx logs as warning
+* All 5xx logs as error
+* Use structured format
+* Store in rotating log files
+* Provide hooks for Sentry in production
+
+---
+
+# **6. Unified Request Payload Rules**
+
+All endpoints must follow:
+
+* snake_case field names
+* predictable field groups
+* standardized pagination params
+* standardized filters
+* standardized bulk update patterns
+* standardized action payloads
+* standardized error messages
+
+**Bulk actions:**
+
+```
+{ "ids": [1,2,3], ... }
+```
+
+**Filtering:**
+
+```
+?search=  
+?status=  
+?site_id=  
+?sector_id=
+```
+
+---
+
+# **7. Tenant / Site / Sector Scoping Rules**
+
+Every resource created or fetched must be scoped by:
+
+1. **Account/Tenant**
+2. **Site**
+3. **Sector**
+
+### Enforcement:
+
+* `AccountModelViewSet` handles account isolation
+* `SiteSectorModelViewSet` filters queries by site/sector
+* All custom actions must also use `.get_queryset()` to avoid bypassing filters
+* Any ID list must be verified to belong to the authenticated tenant
+
+---
+
+# **8. Module-Wise API Rules (Planner / Writer / System / Billing)**
+
+## **Planner Module**
+
+Covers keywords → clusters → ideas.
+
+Rules:
+
+* All endpoints require authentication
+* Auto-cluster limited to 20 keywords/request
+* Ideas generation limited to 1 cluster/request
+* Standardized payloads for imports/exports
+* Bulk actions must validate tenant ownership
+
+---
+
+## **Writer Module**
+
+Covers tasks → content → image prompts → images.
+
+Rules:
+
+* 1 AI content generation per task
+* 1 image generation per request
+* Bulk actions max 50
+* Image prompt extraction uses unified response
+* Must align with progress tracking
+
+---
+
+## **System Module**
+
+Covers prompts, strategies, profiles, integrations, task progress.
+
+Rules:
+
+* Saving prompts requires editor/admin
+* Integration settings require admin/owner
+* All tests (OpenAI/Runware) return unified format
+* Progress endpoint returns stable JSON for progress modal
+
+---
+
+## **Billing Module**
+
+Covers credit balance, usage logs, transactions.
+
+Rules:
+
+* Balance/usage require authenticated tenant
+* Transactions require admin/owner
+* Unified reporting structure
+* No raw model data returned
+
+---
+
+# **9. API Governance, Rate Limits, and Safety Controls**
+
+### **Soft limits**
+
+* 50 tasks per bulk action
+* 20 keywords per cluster batch
+* 1 cluster → ideas generation
+* 1 content → image prompt extraction
+* 1 image generation per job
+* Per-tenant throttling (future)
+
+### **Safety checks**
+
+* Validate all IDs belong to tenant
+* Validate dependent records exist
+* Reject oversized payloads
+* Reject invalid site/sector assignments
+* Reject stale/wrong tenant tokens
+
+---
+
+# **10. Logging, Monitoring, and Diagnostics**
+
+### **Backend logging**
+
+* timestamp
+* request_id
+* endpoint
+* user_id
+* account_id
+* status_code
+* error_message
+* traceback for 5xx
+
+### **Frontend Debug Panel Integration**
+
+All responses must support:
+
+* request ID
+* readable error messages
+* consistent progress steps
+* error visibility in real time
+
+---
+
+# **11. Progress Modal Standard (AI Functions)**
+
+All AI functions must output uniform progress metadata:
+
+**Steps example for image prompt extraction**
+
+```
+Smart Image Prompts
+Checking content and image slots
+Mapping Content for X Image Prompts
+Writing Featured Image Prompts
+Writing X In-article Image Prompts
+Assigning Prompts to Slots
+```
+
+Success message:
+
+```
+Featured Image and X In-article Image Prompts ready for image generation
+```
+
+All four AI functions must follow identical UI messaging structure.
+
+---
+
+# **12. Standard Frontend/Plugin Integration Rules**
+
+### **Frontend**
+
+* All responses parsed through the unified envelope
+* 401 triggers logout → redirect to login
+* 403 triggers permission alert
+* Errors read from `.error` or `.errors`
+* Pagination reads `.results`
+
+### **WordPress Plugin**
+
+* Uses the same JWT flow
+* No custom plugin-specific endpoints
+* Uses the app’s `/api/v1/` fully
+* WP only handles mapping + meta assignment
+
+### **3rd-Party APIs**
+
+* Full compatibility with unified format
+* Full access where tenant/permissions allow
+* No special handling needed
+
+---
+
+# **13. Refactor & Migration Plan (One-Time Update)**
+
+1. Introduce unified response wrapper
+2. Replace all custom responses in ViewSets
+3. Inject consistent permission classes
+4. Wrap all exceptions with centralized handler
+5. Update serializers to rely on unified errors
+6. Patch all custom actions to validate payloads
+7. Update app’s frontend API client
+8. Remove deprecated endpoint patterns
+9. Regenerate Postman/OpenAPI schema
+10. Update WordPress plugin integration
+11. Run full-suite regression tests
+
+This whole migration becomes the Phase-4 API refactor inside the IGNY8 full migration pipeline.
+
+---
+
+# **14. Success Criteria**
+
+* Every endpoint returns same envelope
+* All errors fully unified
+* No endpoint leaks raw DRF format
+* No inconsistent auth behavior
+* No inconsistent pagination
+* No inconsistent validation errors
+* Plugin works using same exact API
+* Third-party clients can implement without special rules
+* Frontend debug panel reads everything correctly
+* CRON + automations structured identically
+
+---
+
+# **15. Final Notes**
+
+This consolidated document **replaces all six API planning files**.
+It is now the single standard for:
+
+* Backend implementation
+* Frontend integration
+* Plugin development
+* External API docs
+* AI function progress UI
+* DevOps & monitoring