paths:
  # ─────────────────────────────────────────────────────────
  # ADMIN — KYB REVIEW MANAGEMENT
  # ─────────────────────────────────────────────────────────
  /admin/kyb:
    get:
      summary: Get all KYB applications
      description: Returns all merchant KYB applications. SuperAdmin can filter by status.
      tags: [KYB — Admin]
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: status
          schema:
            type: string
            enum: [Draft, Submitted, Under Review, Additional Documents Required, Approved, Rejected]
          description: Optional filter by status
      responses:
        '200':
          description: List of applications
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object

  /admin/kyb/{id}:
    get:
      summary: Get a single KYB application
      description: Returns the full details of a single KYB application including documents, directors, and history logs.
      tags: [KYB — Admin]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Full KYB application details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/KybApplication'

  /admin/kyb/{id}/status:
    patch:
      summary: Update KYB application status
      description: |
        SuperAdmin can update the status of the application. 
        - If 'Rejected' or 'Additional Documents Required', a reason MUST be provided.
        - Triggers automatic email notification to the Merchant.
      tags: [KYB — Admin]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status:
                  type: string
                  enum: [Under Review, Additional Documents Required, Approved, Rejected]
                reason:
                  type: string
                  description: Required if status is Rejected or Additional Documents Required
                documentIdToReject:
                  type: string
                  format: uuid
                  description: Optional ID of a specific document to mark as rejected.
      responses:
        '200':
          description: Status updated successfully
        '400':
          description: Invalid status or missing reason

  # ─────────────────────────────────────────────────────────
  # MERCHANT — KYB SUBMISSION
  # ─────────────────────────────────────────────────────────
  /merchants/kyb:
    get:
      summary: Get my KYB application
      description: |
        Returns the merchant's current KYB application status and data. 
        **Frontend Note**: Call this on mount to check if the user is `Approved`, `Submitted`, or still in `Draft`. If no application exists yet, the backend creates an empty Draft automatically and returns it.
      tags: [KYB — Merchant]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Current KYB application
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/KybApplication'
              example:
                success: true
                data:
                  id: "e4d909c2-909e-4e4c-813f-846c4f923b7a"
                  merchantId: "b52d909c-909e-4e4c-813f-846c4f923b7a"
                  status: "Draft"
                  companyName: null
                  registrationNumber: null
                  diditSessionId: null
                  historyLogs: []

    put:
      summary: Save KYB application draft (Initialization)
      description: |
        Upserts the KYB application details. Always saves the state as "Draft".
        **Frontend Note**: Since we are using Didit.me for the actual heavy lifting (document uploads, IDs), you only need to pass the basic company name and registration number here. Didit handles the rest during the hosted flow.
      tags: [KYB — Merchant]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                companyName:
                  type: string
                  description: "The registered name of the business"
                registrationNumber:
                  type: string
                  description: "The official corporate registration number (e.g., RC Number)"
            example:
              companyName: "Airpero Technologies Limited"
              registrationNumber: "RC1234567"
      responses:
        '200':
          description: Application drafted successfully
          content:
            application/json:
              example:
                success: true
                message: "KYB Application saved as Draft"
                data:
                  id: "e4d909c2-909e-4e4c-813f-846c4f923b7a"
                  status: "Draft"
                  companyName: "Airpero Technologies Limited"
                  registrationNumber: "RC1234567"

  /merchants/kyb/submit:
    post:
      summary: Start KYB verification (Get Didit Link)
      description: |
        Creates a Didit KYB session and returns the hosted verification URL for the merchant to complete their KYB.
        **Frontend Note**: Call this when the user clicks "Start Verification". Take the `verificationUrl` returned in the response and redirect the user's browser to it. Didit handles the UI from there.
      tags: [KYB — Merchant]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Session created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      application:
                        $ref: '#/components/schemas/KybApplication'
                      verificationUrl:
                        type: string
                        format: uri
                        description: The hosted Didit verification URL to redirect the user to.
                      sessionToken:
                        type: string
                        description: The Didit session token.
              example:
                success: true
                message: "KYB session created. Please proceed to the verification URL."
                data:
                  application:
                    id: "e4d909c2-909e-4e4c-813f-846c4f923b7a"
                    status: "Submitted"
                    diditSessionId: "sess_123456789"
                  verificationUrl: "https://hosted.didit.me/session/sess_123456789"
                  sessionToken: "eyJhbGciOiJIUzI1NiIsIn..."
        '400':
          description: Application is already submitted or under review
          content:
            application/json:
              example:
                success: false
                message: "Application is already Submitted."

components:
  schemas:
    KybApplication:
      type: object
      description: "The central record tracking the merchant's KYB state."
      properties:
        id:
          type: string
          format: uuid
        merchantId:
          type: string
          format: uuid
        status:
          type: string
          enum: [Draft, Submitted, Under Review, Additional Documents Required, Approved, Rejected]
          description: "The current status of the KYB verification. Frontend should use this to lock/unlock dashboard features."
        diditSessionId:
          type: string
          description: "The unique session ID connecting this record to the Didit verification system."
        companyName:
          type: string
        registrationNumber:
          type: string
        verificationOutcome:
          type: object
          description: "The final JSON payload returned by Didit after verification (contains AML results, UBOs, etc). Only populated when status is Approved/Rejected/Under Review."
        historyLogs:
          type: array
          items:
            type: object
            properties:
              action:
                type: string
              previousStatus:
                type: string
              newStatus:
                type: string
              comment:
                type: string
              createdAt:
                type: string
                format: date-time
