openapi: 3.0.3
info:
  title: Parent API - Al Rahma Sunday School
  version: 1.1.0
  description: >
    REST API for parent-related functionality in the Al Rahma Sunday School system.  
    All endpoints require JWT authentication using a Bearer token, unless otherwise noted.  
    Each response follows the standard format:

    ```json
    {
      "status": "success|error",
      "message": "string",
      "data": {}
    }
    ```

servers:
  - url: https://alrahmaisgl.org/api/v1

security:
  - BearerAuth: []

tags:
  - name: Parents
    description: Manage parent profiles and accounts
  - name: Students
    description: Access and manage parent’s student data
  - name: Attendance
    description: View attendance history for a parent's children
  - name: Enrollment
    description: Manage enrollments and student registration
  - name: Payments
    description: Retrieve invoices and payment details
  - name: Events
    description: Manage student participation in school events

paths:
  /parents:
    get:
      tags: [Parents]
      summary: List all parents (admin use)
      security:
        - BearerAuth: []
      parameters:
        - name: page
          in: query
          schema: { type: integer, example: 1 }
        - name: per_page
          in: query
          schema: { type: integer, example: 20 }
      responses:
        200:
          description: Paginated list of parents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedParentsResponse'
        401:
          description: Unauthorized

  /parents/{id}:
    get:
      tags: [Parents]
      summary: Get parent details by ID
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        200:
          description: Parent details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Parent'
        404:
          description: Parent not found
        401:
          description: Unauthorized

  /parents/{id}/profile:
    get:
      tags: [Parents]
      summary: Get parent profile
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        200:
          description: Parent profile details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Parent'
    put:
      tags: [Parents]
      summary: Update parent profile
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParentUpdateRequest'
      responses:
        200:
          description: Profile updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicSuccess'

  /parents/{id}/students:
    get:
      tags: [Students]
      summary: Get all students for a parent
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        200:
          description: Student list with details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudentsResponse'
    post:
      tags: [Students]
      summary: Register a new student for this parent
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStudentRequest'
      responses:
        200:
          description: Student created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicSuccess'

  /parents/{id}/students/{studentId}:
    put:
      tags: [Students]
      summary: Update a student's info
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
        - name: studentId
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateStudentRequest'
      responses:
        200:
          description: Student updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicSuccess'
    delete:
      tags: [Students]
      summary: Delete a student
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
        - name: studentId
          in: path
          required: true
          schema: { type: integer }
      responses:
        200:
          description: Student deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicSuccess'

  /parents/{id}/attendance:
    get:
      tags: [Attendance]
      summary: Get student attendance records
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
        - name: school_year
          in: query
          schema: { type: string, example: "2024-2025" }
      responses:
        200:
          description: Attendance records retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttendanceList'
              examples:
                sample:
                  value:
                    status: success
                    message: Attendance data retrieved successfully
                    data:
                      - firstname: Ali
                        lastname: Ahmad
                        date: "2024-10-06"
                        status: present
                        reason: null
                      - firstname: Aisha
                        lastname: Ahmad
                        date: "2024-10-13"
                        status: absent
                        reason: Sick

  /parents/{id}/payments:
    get:
      tags: [Payments]
      summary: Retrieve invoices/payments for parent
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        200:
          description: Payment history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceList'
              examples:
                sample:
                  value:
                    status: success
                    message: Payments retrieved successfully
                    data:
                      - id: 101
                        invoice_number: INV-2025-0001
                        parent_id: 55
                        amount: 550
                        status: unpaid
                        created_at: "2025-08-20 12:00:00"

  /parents/{id}/enrollments:
    get:
      tags: [Enrollment]
      summary: Get enrollment data for parent’s students
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
        - name: school_year
          in: query
          schema: { type: string, example: "2024-2025" }
      responses:
        200:
          description: Enrollment info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrollmentResponse'

  /parents/{id}/enroll-classes:
    get:
      tags: [Enrollment]
      summary: Get data for the enroll classes page
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
        - name: school_year
          in: query
          schema: { type: string, example: "2024-2025" }
      responses:
        200:
          description: Enroll classes data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParentEnrollClassesData'
    post:
      tags: [Enrollment]
      summary: Update enrollments (enroll/withdraw)
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateParentEnrollmentsRequest'
      responses:
        200:
          description: Enrollment updates processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateParentEnrollmentsResponse'

  /parents/{id}/emergency-contacts:
    get:
      tags: [Parents]
      summary: List emergency contacts for parent
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        200:
          description: Emergency contacts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmergencyContactsList'
    post:
      tags: [Parents]
      summary: Create or update an emergency contact
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveEmergencyContactRequest'
      responses:
        200:
          description: Saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicSuccess'

  /parents/{id}/authorized-users:
    get:
      tags: [Parents]
      summary: List authorized users (second parents/guardians)
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        200:
          description: Authorized users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizedUsersList'
    post:
      tags: [Parents]
      summary: Add an authorized user (pending)
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddAuthorizedUserRequest'
      responses:
        200:
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicSuccess'

  /parents/{id}/enroll:
    post:
      tags: [Enrollment]
      summary: Enroll one or more students
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                student_ids:
                  type: array
                  items: { type: integer }
                  example: [5, 6]
      responses:
        200:
          description: Enrollment submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicSuccess'

  /parents/{id}/events:
    get:
      tags: [Events]
      summary: Get events and participation data
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        200:
          description: Events and participation data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventParticipationResponse'
              examples:
                sample:
                  value:
                    status: success
                    message: Event participation data retrieved
                    data:
                      events:
                        - id: 1
                          name: Field Trip
                          amount: 25
                          start_date: "2025-10-20"
                          end_date: "2025-10-20"
                      charges:
                        "12:1":
                          student_id: 12
                          event_id: 1
                          participation: yes
                          charged: 25
                          date: "2025-09-30 10:00:00"

  /parents/{id}/events/update:
    post:
      tags: [Events]
      summary: Update student event participation
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                participation:
                  type: object
                  example:
                    "3:1": "yes"
                    "3:2": "no"
      responses:
        200:
          description: Participation updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicSuccess'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Enter your JSON Web Token here.  
        Example:  
        ```
        Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
        ```

  schemas:
    BasicSuccess:
      type: object
      properties:
        status: { type: string, example: "success" }
        message: { type: string, example: "Operation completed successfully" }
        data: { nullable: true }

    Parent:
      type: object
      properties:
        id: { type: integer }
        firstname: { type: string }
        lastname: { type: string }
        email: { type: string, format: email }
        cellphone: { type: string }
        address_street: { type: string }
        city: { type: string }
        state: { type: string }
        zip: { type: string }

    ParentUpdateRequest:
      type: object
      properties:
        firstname: { type: string }
        lastname: { type: string }
        cellphone: { type: string }
        address_street: { type: string }
        city: { type: string }
        state: { type: string }
        zip: { type: string }

    PaginatedParentsResponse:
      type: object
      properties:
        status: { type: string, example: "success" }
        message: { type: string }
        data:
          type: object
          properties:
            page: { type: integer }
            per_page: { type: integer }
            total: { type: integer }
            data:
              type: array
              items:
                $ref: '#/components/schemas/Parent'

    StudentsResponse:
      type: object
      properties:
        status: { type: string }
        message: { type: string }
        data:
          type: array
          items:
            type: object
            properties:
              id: { type: integer }
              firstname: { type: string }
              lastname: { type: string }
              gender: { type: string }
              dob: { type: string }
              current_class:
                type: object
                properties:
                  class_name: { type: string }
                  section_name: { type: string }
              medical_conditions:
                type: array
                items: { type: string }
              allergies:
                type: array
                items: { type: string }

    AttendanceList:
      type: object
      properties:
        status: { type: string }
        message: { type: string }
        data:
          type: array
          items:
            type: object
            properties:
              firstname: { type: string }
              lastname: { type: string }
              date: { type: string, format: date }
              status: { type: string, enum: [present, absent, late] }
              reason: { type: string, nullable: true }

    InvoiceList:
      type: object
      properties:
        status: { type: string }
        message: { type: string }
        data:
          type: array
          items:
            type: object
            properties:
              id: { type: integer }
              invoice_number: { type: string }
              parent_id: { type: integer }
              amount: { type: number }
              status: { type: string }
              created_at: { type: string }

    EnrollmentResponse:
      type: object
      properties:
        status: { type: string }
        message: { type: string }
        data:
          type: array
          items:
            type: object
            properties:
              id: { type: integer }
              firstname: { type: string }
              lastname: { type: string }
              enrollment:
                type: object
                properties:
                  enrollment_status: { type: string }
                  admission_status: { type: string, nullable: true }

    EventParticipationResponse:
      type: object
      properties:
        status: { type: string }
        message: { type: string }
        data:
          type: object
          properties:
            events:
              type: array
              items:
                type: object
                properties:
                  id: { type: integer }
                  name: { type: string }
                  amount: { type: number }
                  start_date: { type: string }
                  end_date: { type: string }
            charges:
              type: object
              additionalProperties:
                type: object
                properties:
                  student_id: { type: integer }
                  event_id: { type: integer }
                  participation: { type: string, enum: [yes, no] }
                  charged: { type: number }
                  date: { type: string, format: date-time }

    CreateStudentRequest:
      type: object
      properties:
        firstname: { type: string }
        lastname: { type: string }
        dob: { type: string, format: date }
        age: { type: integer }
        gender: { type: string }
        registration_grade: { type: string }
        photo_consent: { type: integer, enum: [0,1] }
        rfid_tag: { type: string }
        is_new: { type: integer, enum: [0,1], default: 1 }

    UpdateStudentRequest:
      allOf:
        - $ref: '#/components/schemas/CreateStudentRequest'

    EmergencyContactsList:
      type: object
      properties:
        status: { type: string }
        message: { type: string }
        data:
          type: array
          items:
            type: object
            properties:
              id: { type: integer }
              parent_id: { type: integer }
              emergency_contact_name: { type: string }
              cellphone: { type: string }
              email: { type: string }
              relation: { type: string }

    SaveEmergencyContactRequest:
      type: object
      properties:
        id: { type: integer, nullable: true }
        emergency_contact_name: { type: string }
        cellphone: { type: string }
        email: { type: string, nullable: true }
        relation: { type: string, nullable: true }

    AuthorizedUsersList:
      type: object
      properties:
        status: { type: string }
        message: { type: string }
        data:
          type: array
          items:
            type: object
            properties:
              id: { type: integer }
              user_id: { type: integer }
              firstname: { type: string }
              lastname: { type: string }
              email: { type: string }
              phone_number: { type: string }
              relation_to_user: { type: string }
              status: { type: string }

    AddAuthorizedUserRequest:
      type: object
      required: [firstname, lastname, email, phone_number]
      properties:
        firstname: { type: string }
        lastname: { type: string }
        email: { type: string }
        phone_number: { type: string }
        relation_to_user: { type: string }

    ParentEnrollClassesData:
      type: object
      properties:
        status: { type: string }
        message: { type: string }
        data:
          type: object
          properties:
            students:
              type: array
              items:
                type: object
                properties:
                  id: { type: integer }
                  firstname: { type: string }
                  lastname: { type: string }
                  class_section: { type: string }
                  admission_status: { type: string, nullable: true }
                  enrollment_status: { type: string }
                  disable_enroll: { type: boolean }
            schoolYears:
              type: array
              items:
                type: object
                properties:
                  school_year: { type: string }
            selectedYear: { type: string }
            isEditable: { type: boolean }
            withdrawalDeadline: { type: string, format: date }
            lastDayOfRegistration: { type: string, format: date }
            schoolStartDate: { type: string, format: date }

    UpdateParentEnrollmentsRequest:
      type: object
      properties:
        enroll:
          type: array
          items: { type: integer }
          example: [101, 102]
        withdraw:
          type: array
          items: { type: integer }
          example: [103]

    UpdateParentEnrollmentsResponse:
      type: object
      properties:
        status: { type: string }
        message: { type: string }
        data:
          type: object
          properties:
            enrolled:
              type: array
              items: { type: integer }
            withdrawn:
              type: array
              items: { type: integer }
            messages:
              type: array
              items: { type: string }