{
  "openapi": "3.0.0",
  "info": {
    "title": "Migrant Mobile API",
    "description": "Comprehensive API endpoints for the Migrant Mobile Application, covering worker registration, password login, token authentication, profile management, and interactive job offer responses.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "/api",
      "description": "Local development API prefix"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/workers/register": {
      "post": {
        "tags": [
          "Worker/Auth"
        ],
        "summary": "Register Worker & Upload Documents (Unified API)",
        "description": "Performs worker registration and uploads their passport/visa documents in a single, robust multipart form request. Generates and returns a secure stateless bearer token upon success. Password is required (min 6 characters).",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "phone",
                  "salary",
                  "password",
                  "passport_file"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Amina Al-Masry",
                    "description": "Full legal name of the worker. (REQUIRED)"
                  },
                  "phone": {
                    "type": "string",
                    "example": "+971509998888",
                    "description": "Contact mobile phone number (must be unique). (REQUIRED)"
                  },
                  "salary": {
                    "type": "number",
                    "format": "float",
                    "example": 1500.00,
                    "description": "Desired minimum monthly salary in AED. (REQUIRED)"
                  },
                  "password": {
                    "type": "string",
                    "format": "password",
                    "example": "securepassword123",
                    "description": "Secret password for subsequent mobile logins (min 6 chars). (REQUIRED)"
                  },
                  "passport_file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Physical scan or image of the Passport (Max 10MB). (REQUIRED)"
                  },
                  "skills": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    },
                    "example": [6, 8],
                    "description": "Optional array of Skill IDs (can be sent as comma-separated string e.g. '6,8' or json '[6,8]' in multipart)."
                  },
                  "visa_file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Optional physical scan or image of the Visa (Max 10MB)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Worker registered and authenticated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Worker registered and authenticated successfully."
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "worker": {
                          "$ref": "#/components/schemas/Worker"
                        },
                        "token": {
                          "type": "string",
                          "example": "abc123xyz456...secureToken..."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error details.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": false
                    },
                    "message": {
                      "type": "string",
                      "example": "Validation error."
                    },
                    "errors": {
                      "type": "object",
                      "properties": {
                        "phone": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "example": [
                            "This mobile number is already registered."
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/workers/login": {
      "post": {
        "tags": [
          "Worker/Auth"
        ],
        "summary": "Authenticate Worker",
        "description": "Validates worker credentials (mobile phone number and password) and generates a secure, stateless Bearer token for api access.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "phone",
                  "password"
                ],
                "properties": {
                  "phone": {
                    "type": "string",
                    "example": "+971509998888",
                    "description": "Registered mobile phone number."
                  },
                  "password": {
                    "type": "string",
                    "format": "password",
                    "example": "securepassword123",
                    "description": "Secret account password."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Worker logged in successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Worker logged in successfully."
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "worker": {
                          "$ref": "#/components/schemas/Worker"
                        },
                        "token": {
                          "type": "string",
                          "example": "abc123xyz456...secureToken..."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized access.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": false
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid mobile number or password."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/workers/profile": {
      "get": {
        "tags": [
          "Worker/Profile"
        ],
        "summary": "Get Profile details",
        "description": "Retrieves the authenticated worker's profile details including their selected job category, connected skills, and uploaded documents.",
        "responses": {
          "200": {
            "description": "Worker profile details retrieved.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "worker": {
                          "$ref": "#/components/schemas/Worker"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/workers/profile/update": {
      "post": {
        "tags": [
          "Worker/Profile"
        ],
        "summary": "Update Profile details",
        "description": "Allows workers to customize and complete their profiles by updating age, nationality, desired salary, bio, availability, experience, religion, categories, and master skills list.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Amina Al-Masry"
                  },
                  "age": {
                    "type": "integer",
                    "example": 28
                  },
                  "nationality": {
                    "type": "string",
                    "example": "Egypt"
                  },
                  "salary": {
                    "type": "number",
                    "example": 1800.00
                  },
                  "availability": {
                    "type": "string",
                    "example": "Immediate"
                  },
                  "experience": {
                    "type": "string",
                    "example": "4 Years"
                  },
                  "religion": {
                    "type": "string",
                    "example": "Muslim"
                  },
                  "bio": {
                    "type": "string",
                    "example": "Highly certified housekeeper and babysitter with cooking experience."
                  },
                  "category_id": {
                    "type": "integer",
                    "example": 8
                  },
                  "skills": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    },
                    "example": [6, 8]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Profile updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Profile updated successfully."
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "worker": {
                          "$ref": "#/components/schemas/Worker"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/workers/offers": {
      "get": {
        "tags": [
          "Worker/Offers"
        ],
        "summary": "View Received Job Offers",
        "description": "Returns a list of all custom job/hiring offers received by the worker from different employers (e.g. Work Date, location, salaries, and notes).",
        "responses": {
          "200": {
            "description": "List of job offers retrieved.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "offers": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/JobOffer"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/workers/offers/{id}/respond": {
      "post": {
        "tags": [
          "Worker/Offers"
        ],
        "summary": "Accept or Reject Job Offer",
        "description": "Responds to a pending job offer. If accepted, the job offer status becomes 'accepted' and the worker's status is automatically changed to 'Hired', which reflects immediately in the Employer panel.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The Job Offer ID reference.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "status"
                ],
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "accepted",
                      "rejected"
                    ],
                    "example": "accepted",
                    "description": "Response action (accepted or rejected)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Job offer response saved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Job offer successfully accepted."
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "offer": {
                          "$ref": "#/components/schemas/JobOffer"
                        },
                        "worker_status": {
                          "type": "string",
                          "example": "Hired"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/workers/conversations": {
      "get": {
        "tags": [
          "Worker/Conversations"
        ],
        "summary": "Get Conversations List (Worker)",
        "description": "Retrieves all active conversations for the authenticated worker.",
        "responses": {
          "200": {
            "description": "Conversations list retrieved successfully."
          }
        }
      }
    },
    "/workers/conversations/{id}/messages": {
      "get": {
        "tags": [
          "Worker/Conversations"
        ],
        "summary": "Get Conversation Messages (Worker)",
        "description": "Retrieves message history for a conversation and marks incoming employer messages as read.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Messages retrieved successfully."
          }
        }
      },
      "post": {
        "tags": [
          "Worker/Conversations"
        ],
        "summary": "Send Reply Message (Worker)",
        "description": "Sends a reply message from the worker to the employer.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "example": "Yes, I am available."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Message sent successfully."
          }
        }
      }
    },
    "/employers/register": {
      "post": {
        "tags": [
          "Employer/Auth"
        ],
        "summary": "Register Sponsor (Alias)",
        "description": "Legacy route matching the simplified sponsor registration (Name, Email, Phone).",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "email",
                  "phone"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Ahmad Bin Ahmed",
                    "description": "Sponsor's full name"
                  },
                  "email": {
                    "type": "string",
                    "example": "ahmad@example.com",
                    "description": "Sponsor's contact email address"
                  },
                  "phone": {
                    "type": "string",
                    "example": "+971509990001",
                    "description": "Sponsor's mobile phone number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Sponsor registered successfully."
          }
        }
      }
    },
    "/sponsors/register": {
      "post": {
        "tags": [
          "Sponsor/Auth"
        ],
        "summary": "Register Sponsor",
        "description": "Registers a new sponsor profile with basic info (Name, Email, Phone).",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "email",
                  "phone"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Ahmad Bin Ahmed",
                    "description": "Sponsor's full name"
                  },
                  "email": {
                    "type": "string",
                    "example": "ahmad@example.com",
                    "description": "Sponsor's contact email address"
                  },
                  "phone": {
                    "type": "string",
                    "example": "+971509990001",
                    "description": "Sponsor's mobile phone number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Sponsor registered successfully."
          }
        }
      }
    },
    "/employers/verify": {
      "post": {
        "tags": [
          "Employer/Auth"
        ],
        "summary": "Verify Sponsor Email OTP",
        "description": "Verifies the email address with the OTP verification code (Step 2).",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "otp"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "example": "ahmad@example.com"
                  },
                  "otp": {
                    "type": "string",
                    "example": "111111",
                    "description": "6-digit OTP code"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email verified successfully."
          }
        }
      }
    },
    "/sponsors/verify": {
      "post": {
        "tags": [
          "Sponsor/Auth"
        ],
        "summary": "Verify Sponsor Email OTP (Sponsor Prefix)",
        "description": "Verifies the email address with the OTP verification code (Step 2).",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "otp"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "example": "ahmad@example.com"
                  },
                  "otp": {
                    "type": "string",
                    "example": "111111",
                    "description": "6-digit OTP code"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email verified successfully."
          }
        }
      }
    },
    "/employers/payment": {
      "post": {
        "tags": [
          "Employer/Auth"
        ],
        "summary": "Sponsor Subscription Payment",
        "description": "Submits a successful plan selection and PayTabs payment confirmation (Step 3).",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "plan_id",
                  "amount_aed",
                  "paytabs_transaction_id"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "example": "ahmad@example.com"
                  },
                  "plan_id": {
                    "type": "string",
                    "example": "premium"
                  },
                  "amount_aed": {
                    "type": "number",
                    "example": 199.00
                  },
                  "paytabs_transaction_id": {
                    "type": "string",
                    "example": "TXN998877"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscription payment confirmed."
          }
        }
      }
    },
    "/sponsors/payment": {
      "post": {
        "tags": [
          "Sponsor/Auth"
        ],
        "summary": "Sponsor Subscription Payment (Sponsor Prefix)",
        "description": "Submits a successful plan selection and PayTabs payment confirmation (Step 3).",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "plan_id",
                  "amount_aed",
                  "paytabs_transaction_id"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "example": "ahmad@example.com"
                  },
                  "plan_id": {
                    "type": "string",
                    "example": "premium"
                  },
                  "amount_aed": {
                    "type": "number",
                    "example": 199.00
                  },
                  "paytabs_transaction_id": {
                    "type": "string",
                    "example": "TXN998877"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscription payment confirmed."
          }
        }
      }
    },
    "/employers/password": {
      "post": {
        "tags": [
          "Employer/Auth"
        ],
        "summary": "Create Sponsor Account Password",
        "description": "Configures and finalizes the portal login password to complete registration (Step 4). Returns bearer token.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password",
                  "password_confirmation"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "example": "ahmad@example.com"
                  },
                  "password": {
                    "type": "string",
                    "format": "password",
                    "example": "Password@123"
                  },
                  "password_confirmation": {
                    "type": "string",
                    "format": "password",
                    "example": "Password@123"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Password set and registration finalized successfully."
          }
        }
      }
    },
    "/sponsors/password": {
      "post": {
        "tags": [
          "Sponsor/Auth"
        ],
        "summary": "Create Sponsor Account Password (Sponsor Prefix)",
        "description": "Configures and finalizes the portal login password to complete registration (Step 4). Returns bearer token.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password",
                  "password_confirmation"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "example": "ahmad@example.com"
                  },
                  "password": {
                    "type": "string",
                    "format": "password",
                    "example": "Password@123"
                  },
                  "password_confirmation": {
                    "type": "string",
                    "format": "password",
                    "example": "Password@123"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Password set and registration finalized successfully."
          }
        }
      }
    },
    "/employers/plans": {
      "get": {
        "tags": [
          "Employer/Auth"
        ],
        "summary": "Get Available Subscription Plans",
        "description": "Returns details (price, features) of subscription packages available to sponsors.",
        "security": [],
        "responses": {
          "200": {
            "description": "Subscription plans list retrieved successfully."
          }
        }
      }
    },
    "/sponsors/plans": {
      "get": {
        "tags": [
          "Sponsor/Auth"
        ],
        "summary": "Get Available Subscription Plans (Sponsor Prefix)",
        "description": "Returns details (price, features) of subscription packages available to sponsors.",
        "security": [],
        "responses": {
          "200": {
            "description": "Subscription plans list retrieved successfully."
          }
        }
      }
    },
    "/employers/login": {
      "post": {
        "tags": [
          "Employer/Auth"
        ],
        "summary": "Authenticate Employer",
        "description": "Validates employer email and password and returns a stateless Bearer token.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "example": "ahmad@example.com"
                  },
                  "password": {
                    "type": "string",
                    "example": "Password@123"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Employer logged in successfully."
          }
        }
      }
    },
    "/employers/conversations": {
      "get": {
        "tags": [
          "Employer/Conversations"
        ],
        "summary": "Get Conversations List (Employer)",
        "description": "Retrieves all active candidate conversations for the authenticated employer.",
        "responses": {
          "200": {
            "description": "Conversations list retrieved successfully."
          }
        }
      }
    },
    "/employers/conversations/{id}/messages": {
      "get": {
        "tags": [
          "Employer/Conversations"
        ],
        "summary": "Get Conversation Messages (Employer)",
        "description": "Retrieves message history for a conversation and marks incoming worker messages as read.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Messages retrieved successfully."
          }
        }
      },
      "post": {
        "tags": [
          "Employer/Conversations"
        ],
        "summary": "Send Reply Message (Employer)",
        "description": "Sends a reply message from the employer to the worker.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "example": "When can you start?"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Message sent successfully."
          }
        }
      }
    },
    "/employers/conversations/start": {
      "post": {
        "tags": [
          "Employer/Conversations"
        ],
        "summary": "Start Conversation with Worker",
        "description": "Starts or retrieves a conversation with the specified worker ID.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "worker_id"
                ],
                "properties": {
                  "worker_id": {
                    "type": "integer",
                    "example": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Conversation started successfully."
          }
        }
      }
    },
    "/workers/announcements": {
      "get": {
        "tags": [
          "Worker/CharityEvents"
        ],
        "summary": "Get Charity Events (Worker)",
        "description": "Allows workers to retrieve the list of active charity events, food drives, and medical support programs scheduled in Dubai.",
        "responses": {
          "200": {
            "description": "List of charity events retrieved successfully."
          }
        }
      }
    },
    "/employers/announcements": {
      "get": {
        "tags": [
          "Employer/CharityEvents"
        ],
        "summary": "Get Posted Charity Events (Employer)",
        "description": "Allows employers/sponsors to retrieve the list of charity events they have published.",
        "responses": {
          "200": {
            "description": "List of posted charity events retrieved successfully."
          }
        }
      },
      "post": {
        "tags": [
          "Employer/CharityEvents"
        ],
        "summary": "Publish Charity Event (Employer)",
        "description": "Allows employers/sponsors to publish a new community charity event or drive to all workers in Dubai, triggering instant push notifications and morning-of reminders.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title",
                  "content",
                  "provided_items",
                  "event_date",
                  "event_time",
                  "location_details",
                  "location_pin"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "example": "Free Dental Checkup Camp"
                  },
                  "content": {
                    "type": "string",
                    "example": "Emirates Charity is providing free professional dental screening, cleanings, and educational packages for domestic helpers."
                  },
                  "provided_items": {
                    "type": "string",
                    "example": "Free Dental screening, cleanings, and wellness kits"
                  },
                  "event_date": {
                    "type": "string",
                    "format": "date",
                    "example": "2026-06-15"
                  },
                  "event_time": {
                    "type": "string",
                    "example": "9:00 AM - 4:00 PM"
                  },
                  "location_details": {
                    "type": "string",
                    "example": "Al Quoz Community Hall, Dubai"
                  },
                  "location_pin": {
                    "type": "string",
                    "format": "uri",
                    "example": "https://maps.app.goo.gl/xyz"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Charity event created and notifications scheduled successfully."
          }
        }
      }
    },
    "/employers/announcements/{id}": {
      "delete": {
        "tags": [
          "Employer/CharityEvents"
        ],
        "summary": "Delete Charity Event (Employer)",
        "description": "Allows employers/sponsors to delete a previously published charity event.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Charity event deleted successfully."
          }
        }
      }
    },
    "/employers/profile": {
      "get": {
        "tags": [
          "Employer/Profile"
        ],
        "summary": "Get Profile details (Employer)",
        "description": "Retrieves the authenticated employer's profile details including their selected company name, phone, language preference, and notification settings.",
        "responses": {
          "200": {
            "description": "Employer profile details retrieved successfully."
          }
        }
      }
    },
    "/employers/profile/update": {
      "post": {
        "tags": [
          "Employer/Profile"
        ],
        "summary": "Update Profile details (Employer)",
        "description": "Allows employers to update their profile details (company name, phone number, name, email, language preference, and notification settings) and change their account password.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "email",
                  "phone",
                  "company_name",
                  "language",
                  "notifications"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Ahmad"
                  },
                  "email": {
                    "type": "string",
                    "example": "ahmad@example.com"
                  },
                  "phone": {
                    "type": "string",
                    "example": "+971509990001"
                  },
                  "company_name": {
                    "type": "string",
                    "example": "Ahmad Tech Ltd"
                  },
                  "language": {
                    "type": "string",
                    "enum": [
                      "English",
                      "Arabic"
                    ],
                    "example": "English"
                  },
                  "notifications": {
                    "type": "boolean",
                    "example": true
                  },
                  "current_password": {
                    "type": "string",
                    "example": "Password@123"
                  },
                  "new_password": {
                    "type": "string",
                    "example": "NewSecurePassword@123"
                  },
                  "new_password_confirmation": {
                    "type": "string",
                    "example": "NewSecurePassword@123"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Profile updated successfully."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "Worker": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 136
          },
          "name": {
            "type": "string",
            "example": "Amina Al-Masry"
          },
          "email": {
            "type": "string",
            "example": "worker.971509998888@migrant.com"
          },
          "phone": {
            "type": "string",
            "example": "+971509998888"
          },
          "nationality": {
            "type": "string",
            "example": "Egypt"
          },
          "age": {
            "type": "integer",
            "example": 28
          },
          "salary": {
            "type": "string",
            "example": "1500.00"
          },
          "availability": {
            "type": "string",
            "example": "Immediate"
          },
          "experience": {
            "type": "string",
            "example": "4 Years"
          },
          "religion": {
            "type": "string",
            "example": "Muslim"
          },
          "bio": {
            "type": "string",
            "example": "Certified infant caregiver and housekeeper with excellent cooking skills."
          },
          "category_id": {
            "type": "integer",
            "example": 7
          },
          "verified": {
            "type": "boolean",
            "example": false
          },
          "status": {
            "type": "string",
            "example": "active"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-05-20T14:54:26.000000Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-05-20T14:54:26.000000Z"
          },
          "category": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "example": 7
              },
              "name": {
                "type": "string",
                "example": "General Helper"
              }
            }
          },
          "skills": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "example": 6
                },
                "name": {
                  "type": "string",
                  "example": "Cleaning"
                }
              }
            }
          },
          "documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WorkerDocument"
            }
          }
        }
      },
      "WorkerDocument": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 15
          },
          "worker_id": {
            "type": "integer",
            "example": 136
          },
          "type": {
            "type": "string",
            "example": "passport"
          },
          "number": {
            "type": "string",
            "example": "P345892"
          },
          "issue_date": {
            "type": "string",
            "format": "date",
            "example": "2024-05-20"
          },
          "expiry_date": {
            "type": "string",
            "format": "date",
            "example": "2034-05-20"
          },
          "ocr_accuracy": {
            "type": "number",
            "example": 98.5
          },
          "file_path": {
            "type": "string",
            "example": "uploads/documents/1716200000_passport_my_file.jpg"
          }
        }
      },
      "JobOffer": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1
          },
          "employer_id": {
            "type": "integer",
            "example": 2
          },
          "worker_id": {
            "type": "integer",
            "example": 136
          },
          "work_date": {
            "type": "string",
            "format": "date",
            "example": "2026-06-01"
          },
          "location": {
            "type": "string",
            "example": "Dubai Marina, Silverene Towers"
          },
          "salary": {
            "type": "string",
            "example": "2500.00"
          },
          "notes": {
            "type": "string",
            "example": "Require housekeeping support starting from June 1st."
          },
          "status": {
            "type": "string",
            "example": "pending"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-05-20T15:23:44.000000Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-05-20T15:23:44.000000Z"
          }
        }
      }
    }
  }
}
