openapi: 3.1.0
info:
  title: Aiwyn API
  version: 1.0.0
  description: >
    # Welcome to Aiwyn API


    The Aiwyn API provides programmatic access to our comprehensive suite of
    financial automation tools.

    Build powerful integrations and automate your accounting workflows with our
    RESTful APIs.


    ## Key Features


    - 🔐 **Secure Authentication** - Industry-standard OAuth 2.0 and API key
    authentication

    - 📊 **Real-time Data** - Access up-to-date financial information

    - 🚀 **High Performance** - Low latency, high throughput API infrastructure

    - 📚 **Comprehensive Coverage** - Full access to clients, engagements,
    expenses, and more

    - 🛠️ **Developer-Friendly** - Extensive documentation, SDKs, and code
    examples


    ## API Versioning


    We use URL versioning for our APIs. The current version is `v1`. All
    endpoints are prefixed with the version number.
  contact:
    name: Aiwyn API Support
    email: api-support@aiwyn.com
    url: https://www.aiwyn.ai/
servers:
  - url: https://demo.api.aiwyn.ai
    description: Staging Environment (Test Data)
security:
  - BearerAuth: []
tags:
  - name: Authentication
    description: >
      Authentication endpoints for obtaining access tokens and managing API
      keys.
    x-displayName: 🔐 Authentication
  - name: Client
    description: |
      Manage client records, profiles, and related operations.
    x-displayName: 👤 Client
  - name: Contact
    description: |
      Manage contact information and relationships for clients.
    x-displayName: 📇 Contact
  - name: Staff
    description: |
      Manage staff accounts, roles, and permissions.
    x-displayName: 🧑‍💼 Staff
  - name: Payments
    description: |
      Handle incoming and outgoing payments.
    x-displayName: 💳 Payments
  - name: Billing
    description: |
      Manage billing cycles, statements, and billing configurations.
    x-displayName: 🧾 Billing
  - name: Invoices
    description: |
      Create, send, and manage invoices.
    x-displayName: 📄 Invoices
  - name: Projects
    description: |
      Handle engagements, projects, and workflow tracking.
    x-displayName: 📋 Projects
  - name: Time
    description: |
      Track and manage billable and non-billable time entries.
    x-displayName: ⏱ Time
  - name: Engagement
    description: |
      Create, send, and track engagement.
    x-displayName: ✉️ Engagement
  - name: Last Mile
    description: |
      Handle the final delivery stage and client closing processes.
    x-displayName: 🛤 Last Mile
paths:
  /v1/auth/token:
    post:
      tags:
        - Authentication
      summary: Generate API Token
      description: |
        Exchange an jwt Api Key to generate an API Token for accessing
        Product APIs.
      operationId: generateApiToken
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                jwtApiKey:
                  type: string
                  description: jwtApiKey Key obtained from Aiwyn Support.
              required:
                - jwtApiKey
      responses:
        '200':
          description: API Token generated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: JWT Token for accessing Product APIs.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /gql/v1/draft_invoice_histories:
    post:
      tags:
        - Billing
      summary: List draft invoice histories
      description: |
        **Retrieve draft invoice histories with basic pagination support**

        Provides paginated access to draft invoice history records.

        Real Example:
        ```bash
        curl --location 'https://{{host}}/v1/draft_invoice_histories' \
        --header 'Authorization: bearer {{token}}' \
        --header 'Content-Type: application/json' \
        --data '{
          "pageSize": 25,
          "page": 0
        }'
        ```
      operationId: getDraftInvoiceHistoriesPaginated
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                pageSize:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 50
                  description: Maximum number of records to return
                page:
                  type: integer
                  minimum: 0
                  default: 0
                  description: Number of records to skip for pagination
            examples:
              default_pagination:
                summary: Default pagination
                value:
                  pageSize: 25
                  page: 0
      responses:
        '200':
          description: Successfully retrieved draft invoice histories
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DraftInvoiceHistoryListResponse'
              examples:
                successful_response:
                  summary: >-
                    Draft invoice histories with client and draft invoice
                    details
                  value:
                    draftInvoices:
                      - clientId: 7720
                        invoiceId: 125890
                        jobId: 2514
                        client:
                          active: true
                          clientRef: TF-2024-789
                          name: TechFlow Enterprises
                          pmsRef: '240815'
                        draftInvoice:
                          approvedAt: '2024-03-15T14:32:18+00:00'
                          arTranId: 125890
                          approverStaffId: 301
                          approvedByStaffId: 301
                          invoiceId: 125890
                          isActive: true
                          pms_invoice_number: INV-2024-4850
                          status: APPROVED
                    total:
                      aggregate:
                        count: 94
        '400':
          description: Bad request - invalid pagination parameters
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /gql/v1/draft_invoice_histories/search:
    post:
      tags:
        - Billing
      summary: Search draft invoice histories
      description: >
        **Advanced draft invoice history filtering with custom GraphQL where
        clauses and dynamic ordering**


        Supports client, invoice, job filtering and draftInvoice approvedAt date
        range.


        Real Example:

        ```bash

        curl --location 'https://{{host}}/v1/draft_invoice_histories/search' \

        --header 'Authorization: bearer {{token}}' \

        --header 'Content-Type: application/json' \

        --data '{
          "pageSize": 1,
          "where": {
            "_and": [
              {
                "_or": [
                  {
                    "clientId": {
                      "_in": [1001, 1002]
                    }
                  },
                  {
                    "jobId": {
                      "_in": [2001, 2002]
                    }
                  }
                ]
              },
              {
                "active": {
                  "_eq": true
                }
              },
              {
                "createdAt": {
                  "_gte": "1900-01-01T00:00:00Z"
                }
              },
              {
                "activityType": {
                  "_in": [
                    "DRAFT_INVOICE_CREATED",
                    "DRAFT_INVOICE_RECONCILED"
                  ]
                }
              }
            ]
          },
          "orderBy": [
            {
              "clientId": "asc"
            },
            {
              "createdAt": "desc"
            }
          ]
        }'

        ```
      operationId: filterDraftInvoiceHistoriesDynamic
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                pageSize:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 1
                where:
                  type: object
                  description: GraphQL-style where clause for complex filtering
                  example:
                    _and:
                      - _or:
                          - clientId:
                              _in:
                                - 1001
                                - 1002
                          - jobId:
                              _in:
                                - 2001
                                - 2002
                      - active:
                          _eq: true
                      - createdAt:
                          _gte: '1900-01-01T00:00:00Z'
                      - activityType:
                          _in:
                            - DRAFT_INVOICE_CREATED
                            - DRAFT_INVOICE_RECONCILED
                orderBy:
                  type: array
                  items:
                    type: object
                  description: Dynamic ordering specifications
                  example:
                    - clientId: asc
                    - createdAt: desc
      responses:
        '200':
          description: Successfully retrieved filtered draft invoice histories
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DraftInvoiceHistoryListResponse'
              examples:
                successful_response:
                  summary: Filtered draft invoice histories
                  value:
                    draftInvoices:
                      - clientId: 7720
                        invoiceId: 125890
                        jobId: 2514
                        client:
                          active: true
                          clientRef: TF-2024-789
                          name: TechFlow Enterprises
                          pmsRef: '240815'
                        draftInvoice:
                          approvedAt: '2024-03-15T14:32:18+00:00'
                          arTranId: 125890
                          approverStaffId: 301
                          approvedByStaffId: 301
                          invoiceId: 125890
                          isActive: true
                          pms_invoice_number: INV-2024-4850
                          status: APPROVED
                    total:
                      aggregate:
                        count: 12
        '400':
          description: Bad request - invalid where/orderBy
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /gql/v1/draft_invoice/{id}:
    get:
      tags:
        - Billing
      summary: Get draft invoice by ID
      description: |
        **Retrieve a specific draft invoice by its unique identifier**

        This endpoint provides detailed draft invoice information including:
        - Complete draft invoice details and line items
        - Draft status and review information
        - Client and project relationships
        - Tax calculations and compliance data
        - Review history and approval workflow
        - Document generation and delivery preparation

        **Draft Invoice Management Features:**
        - Draft invoice lifecycle tracking
        - Review and approval workflow
        - Tax calculation and compliance
        - Client relationship integration
        - Document preparation and delivery setup

        **Draft Invoice Details Include:**
        - Draft invoice number and reference
        - Draft status and review status
        - Client and project information
        - Line items and amounts
        - Tax calculations
        - Review history

        **Business Applications:**
        - Draft invoice review and approval
        - Tax compliance verification
        - Client billing preparation
        - Revenue recognition planning
        - Document generation preparation

        **Real Example:**
        ```bash
        curl --location 'https://{{host}}/v1/draft_invoice/56789' \
        --header 'Authorization: bearer {{token}}' \
        --header 'Content-Type: application/json'
        ```

        **Response Example:**
        ```json
        {
          "id": 56789,
          "draftNumber": "DRAFT-2024-001",
          "reference": "Q4-AUDIT-DRAFT-2024",
          "status": "UNDER_REVIEW",
          "reviewStatus": "PENDING_APPROVAL",
          "clientId": 789,
          "clientName": "Acme Corporation",
          "clientEmail": "billing@acme.com",
          "projectId": 67890,
          "projectName": "Q4 Financial Audit",
          "preparedDate": "2024-12-01T00:00:00Z",
          "proposedIssueDate": "2024-12-15T00:00:00Z",
          "proposedDueDate": "2025-01-15T23:59:59Z",
          "subtotal": 20000.00,
          "taxAmount": 2000.00,
          "totalAmount": 22000.00,
          "currency": "USD",
          "lineItems": [
            {
              "id": 1,
              "description": "Financial Statement Audit",
              "quantity": 80,
              "unitPrice": 250.00,
              "amount": 20000.00,
              "taxRate": 0.10,
              "notes": "Includes fieldwork and report preparation"
            }
          ],
          "reviewHistory": [
            {
              "id": 1,
              "reviewerId": 123,
              "reviewerName": "John Smith",
              "reviewDate": "2024-12-05T10:30:00Z",
              "status": "APPROVED",
              "comments": "All calculations verified and approved"
            },
            {
              "id": 2,
              "reviewerId": 124,
              "reviewerName": "Jane Doe",
              "reviewDate": "2024-12-06T14:15:00Z",
              "status": "PENDING_APPROVAL",
              "comments": "Pending final review"
            }
          ],
          "notes": "Draft invoice for Q4 audit services - pending final review",
          "createdAt": "2024-12-01T09:00:00Z",
          "updatedAt": "2024-12-06T14:15:00Z"
        }
        ```
      operationId: getDraftInvoiceById
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier of the draft invoice
          schema:
            type: integer
            minimum: 1
          example: 56789
      responses:
        '200':
          description: Draft invoice details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: Unique draft invoice identifier
                    example: 56789
                  draftNumber:
                    type: string
                    description: Draft invoice number
                    example: DRAFT-2024-001
                  reference:
                    type: string
                    description: Draft invoice reference or description
                    example: Q4-AUDIT-DRAFT-2024
                  status:
                    type: string
                    description: Draft invoice status
                    enum:
                      - DRAFT
                      - UNDER_REVIEW
                      - APPROVED
                      - REJECTED
                      - CONVERTED
                    example: UNDER_REVIEW
                  reviewStatus:
                    type: string
                    description: Review status
                    enum:
                      - NOT_STARTED
                      - IN_REVIEW
                      - PENDING_APPROVAL
                      - APPROVED
                      - REJECTED
                    example: PENDING_APPROVAL
                  clientId:
                    type: integer
                    description: Associated client identifier
                    example: 789
                  clientName:
                    type: string
                    description: Client name
                    example: Acme Corporation
                  clientEmail:
                    type: string
                    description: Client billing email
                    example: billing@acme.com
                  projectId:
                    type: integer
                    description: Associated project identifier
                    example: 67890
                  projectName:
                    type: string
                    description: Project name
                    example: Q4 Financial Audit
                  preparedDate:
                    type: string
                    format: date-time
                    description: Date when draft was prepared
                    example: '2024-12-01T00:00:00Z'
                  proposedIssueDate:
                    type: string
                    format: date-time
                    description: Proposed invoice issue date
                    example: '2024-12-15T00:00:00Z'
                  proposedDueDate:
                    type: string
                    format: date-time
                    description: Proposed invoice due date
                    example: '2025-01-15T23:59:59Z'
                  subtotal:
                    type: number
                    format: decimal
                    description: Draft subtotal before tax
                    example: 20000
                  taxAmount:
                    type: number
                    format: decimal
                    description: Total tax amount
                    example: 2000
                  totalAmount:
                    type: number
                    format: decimal
                    description: Total draft amount including tax
                    example: 22000
                  currency:
                    type: string
                    description: Draft currency code
                    example: USD
                  lineItems:
                    type: array
                    description: Draft invoice line items
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Line item identifier
                          example: 1
                        description:
                          type: string
                          description: Line item description
                          example: Financial Statement Audit
                        quantity:
                          type: number
                          format: decimal
                          description: Quantity of units
                          example: 80
                        unitPrice:
                          type: number
                          format: decimal
                          description: Unit price
                          example: 250
                        amount:
                          type: number
                          format: decimal
                          description: Line item total amount
                          example: 20000
                        taxRate:
                          type: number
                          format: decimal
                          description: Tax rate applied
                          example: 0.1
                        notes:
                          type: string
                          description: Additional notes for line item
                          example: Includes fieldwork and report preparation
                  reviewHistory:
                    type: array
                    description: Review history for this draft invoice
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Review record identifier
                          example: 1
                        reviewerId:
                          type: integer
                          description: Reviewer identifier
                          example: 123
                        reviewerName:
                          type: string
                          description: Reviewer name
                          example: John Smith
                        reviewDate:
                          type: string
                          format: date-time
                          description: Review date
                          example: '2024-12-05T10:30:00Z'
                        status:
                          type: string
                          description: Review status
                          enum:
                            - APPROVED
                            - REJECTED
                            - PENDING_APPROVAL
                            - COMMENTS
                          example: APPROVED
                        comments:
                          type: string
                          description: Review comments
                          example: All calculations verified and approved
                  notes:
                    type: string
                    description: Additional notes or terms
                    example: Draft invoice for Q4 audit services - pending final review
                  createdAt:
                    type: string
                    format: date-time
                    description: Draft invoice creation timestamp
                    example: '2024-12-01T09:00:00Z'
                  updatedAt:
                    type: string
                    format: date-time
                    description: Last update timestamp
                    example: '2024-12-06T14:15:00Z'
        '401':
          description: Unauthorized - Invalid or missing authentication token
        '403':
          description: Forbidden - Insufficient permissions to access this draft invoice
        '404':
          description: Draft invoice not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Draft invoice not found
                  message:
                    type: string
                    example: Draft invoice with ID 56789 does not exist
        '500':
          description: Internal server error
  /gql/v1/clients:
    post:
      tags:
        - Client
      summary: List clients
      description: >
        **Retrieve all clients with basic pagination support**


        This endpoint provides simple client listing capabilities without any
        filtering restrictions.

        It's designed for scenarios where you need to browse through the entire
        client database

        with standard pagination controls.


        **Key Features:**

        - Basic pagination with configurable page sizes (default: 50 records)

        - Default sorting by client name (ascending) then creation date
        (descending)  

        - Complete client information including contact details and staff
        assignments

        - Total count aggregation for pagination metadata

        - No filtering logic - returns all clients in the system

        - Optimized for dashboard displays and data export operations


        **Performance Considerations:**

        - Default 50-record pageSize prevents memory issues with large datasets

        - Indexed sorting on name and createdAt fields for optimal query
        performance

        - Consider using filtered queries for large client databases (1000+
        records)

        - Suitable for datasets up to 10,000 clients with reasonable response
        times


        **Real Example:**

        ```bash

        curl --location 'https://{{host}}/v1/clients' \

        --data '{
          "pageSize": 25,
          "page": 0
        }'

        ```
      operationId: getClients
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                pageSize:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 50
                  description: Maximum number of client records to return
                  example: 25
                page:
                  type: integer
                  minimum: 0
                  default: 0
                  description: Number of records to skip for pagination navigation
                  example: 0
            examples:
              default_pagination:
                summary: Default pagination
                value:
                  pageSize: 25
                  page: 0
      responses:
        '200':
          description: Successfully retrieved client list
          content:
            application/json:
              schema:
                type: object
                properties:
                  clients:
                    type: array
                    items:
                      $ref: '#/components/schemas/Client'
                  total:
                    type: object
                    properties:
                      aggregate:
                        type: object
                        properties:
                          count:
                            type: integer
                            description: Total number of clients in the system
                            example: 13697
              examples:
                successful_response:
                  summary: Typical response with client data
                  value:
                    clients:
                      - id: 1001
                        pmsRef: '8842'
                        clientRef: '45123'
                        name: Sarah Johnson
                        clientKey: 000000045123                              f
                        active: true
                        createdAt: '2024-03-15T10:30:22.488054+00:00'
                        updatedAt: '2024-07-20T14:22:10.817274+00:00'
                        clientContactInfo:
                          id: 7001
                          firstName: Sarah
                          lastName: Johnson
                          email: sarah.johnson@techcorp.com
                          phone: 555-0123
                          address: 123 Business Plaza
                          city: San Francisco
                          state: CA
                          zip_code: '94105'
                        partnerStaff:
                          id: 101
                          firstName: Michael
                          lastName: Chen
                          email: m.chen@company.com
                        managerStaff:
                          id: 102
                          firstName: Lisa
                          lastName: Rodriguez
                          email: l.rodriguez@company.com
                      - id: 1002
                        pmsRef: '8843'
                        clientRef: '45124'
                        name: DataFlow Solutions Inc
                        clientKey: 000000045124                              f
                        active: true
                        createdAt: '2024-03-16T09:15:33.660145+00:00'
                        updatedAt: '2024-07-20T14:22:10.817274+00:00'
                        clientContactInfo:
                          id: 7002
                          firstName: Robert
                          lastName: Kim
                          email: r.kim@dataflow.io
                          phone: 555-0124
                          address: 456 Innovation Drive
                          city: Austin
                          state: TX
                          zip_code: '73301'
                        partnerStaff:
                          id: 103
                          firstName: Jennifer
                          lastName: Park
                          email: j.park@company.com
                        managerStaff:
                          id: 104
                          firstName: David
                          lastName: Thompson
                          email: d.thompson@company.com
                      - id: 1003
                        pmsRef: '8844'
                        clientRef: '45125'
                        name: Green Energy Partners
                        clientKey: 000000045125                              f
                        active: true
                        createdAt: '2024-03-17T11:45:11.410185+00:00'
                        updatedAt: '2024-03-17T11:45:11.410185+00:00'
                        clientContactInfo: null
                        partnerStaff:
                          id: 105
                          firstName: Amanda
                          lastName: Williams
                          email: a.williams@company.com
                        managerStaff:
                          id: 105
                          firstName: Amanda
                          lastName: Williams
                          email: a.williams@company.com
                      - id: 1004
                        pmsRef: '8845'
                        clientRef: '45126'
                        name: Metro Healthcare Systems
                        clientKey: 000000045126                              f
                        active: true
                        createdAt: '2024-03-18T08:20:14.232691+00:00'
                        updatedAt: '2024-07-20T14:22:10.817274+00:00'
                        clientContactInfo:
                          id: 7004
                          firstName: Dr. Elena
                          lastName: Martinez
                          email: e.martinez@metrohealthcare.com
                          phone: 555-0126
                          address: 789 Medical Center Blvd
                          city: Denver
                          state: CO
                          zip_code: '80202'
                        partnerStaff:
                          id: 106
                          firstName: Ryan
                          lastName: O'Connor
                          email: r.oconnor@company.com
                        managerStaff:
                          id: 107
                          firstName: Maria
                          lastName: Gonzalez
                          email: m.gonzalez@company.com
                      - id: 1005
                        pmsRef: '8846'
                        clientRef: '45127'
                        name: Pacific Manufacturing Co
                        clientKey: 000000045127                              f
                        active: true
                        createdAt: '2024-03-19T13:12:52.495590+00:00'
                        updatedAt: '2024-07-20T14:22:10.817274+00:00'
                        clientContactInfo:
                          id: 7005
                          firstName: James
                          lastName: Wu
                          email: j.wu@pacificmfg.com
                          phone: 555-0127
                          address: 321 Industrial Way
                          city: Seattle
                          state: WA
                          zip_code: '98101'
                        partnerStaff:
                          id: 108
                          firstName: Nicole
                          lastName: Brown
                          email: n.brown@company.com
                        managerStaff:
                          id: 109
                          firstName: Kevin
                          lastName: Davis
                          email: k.davis@company.com
                    total:
                      aggregate:
                        count: 13697
                empty_response:
                  summary: Empty result set
                  value:
                    clients: []
                    total:
                      aggregate:
                        count: 0
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_page_size:
                  summary: Invalid pageSize parameter
                  value:
                    error: pageSize must be between 1 and 1000
                    code: INVALID_PARAMETER
                negative_page:
                  summary: Negative page
                  value:
                    error: page must be non-negative
                    code: INVALID_PARAMETER
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /gql/v1/clients/search:
    post:
      tags:
        - Client
      summary: Search clients
      description: >
        **Advanced client filtering with custom GraphQL where clauses and
        dynamic ordering**


        This query provides maximum flexibility for client data retrieval
        through custom

        GraphQL-style where clause construction and dynamic ordering
        specifications.

        It's designed for complex business requirements that need sophisticated
        filtering logic.


        **Key Features:**

        - Custom GraphQL where clause construction for unlimited filtering
        combinations

        - Dynamic order_by specifications supporting multi-field sorting with
        custom directions

        - Advanced boolean logic combining multiple filter conditions with _and,
        _or, _not

        - Relationship-based filtering across connected entities (contacts,
        staff assignments)

        - Custom pagination with flexible pageSize and page controls for any
        result set size

        - Full access to GraphQL query capabilities through REST interface
        abstraction

        - Enterprise-grade filtering supporting complex business logic
        requirements

        - Support for nested queries and conditional logic patterns


        **Advanced Filtering Capabilities:**

        - **Boolean Logic**: _and, _or, _not operators for complex condition
        combinations

        - **Text Operations**: _like, _ilike, _regex for pattern matching and
        search

        - **Comparison Operators**: _gt, _gte, _lt, _lte, _eq, _neq for
        numerical/date comparisons  

        - **Array Operations**: _in, _nin for multi-value filtering and
        inclusion/exclusion

        - **Null Handling**: _is_null for empty value detection and filtering

        - **Relationship Traversal**: Filter on connected entities like contacts
        and staff

        - **Date Ranges**: Precision timestamp filtering for time-based analysis

        - **Case Sensitivity**: Both case-sensitive and case-insensitive text
        matching


        **Dynamic Ordering Options:**

        - **Multi-field Sorting**: Order by multiple columns with individual
        sort directions

        - **Relationship Sorting**: Sort by connected entity fields (staff
        names, contact info)

        - **Custom Directions**: Mix ascending and descending order across
        different fields

        - **Priority Ordering**: Define primary, secondary, tertiary sort
        criteria

        - **Date-based Sorting**: createdAt, updatedAt for chronological
        ordering

        - **Text Sorting**: Alphabetical ordering with locale-aware collation


        **Real Example:**

        ```bash

        curl --location 'https://{{host}}/v1/clients/search' \

        --header 'Authorization: bearer {{token}} \

        --header 'Content-Type: application/json' \

        --data '{
          "pageSize": 1,
          "where": {
            "_and": [
              {
                "_or": [
                  {
                    "name": {
                      "_ilike": "%tech%"
                    }
                  },
                  {
                    "clientRef": {
                      "_ilike": "%45%"
                    }
                  }
                ]
              },
              {
                "active": {
                  "_eq": true
                }
              },
              {
                "createdAt": {
                  "_gte": "1900-01-01T00:00:00Z"
                }
              },
              {
                "partnerStaffId": {
                  "_in": [
                    5,
                    6,
                    7,
                    8
                  ]
                }
              }
            ]
          },
          "orderBy": [
            {
              "name": "asc"
            },
            {
              "createdAt": "desc"
            }
          ]
        }'

        ```
      operationId: filterClientsDynamic
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                limit:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 1
                  description: Maximum number of filtered clients to return
                  example: 1
                where:
                  type: object
                  description: GraphQL-style where clause for complex filtering
                  example:
                    _and:
                      - _or:
                          - name:
                              _ilike: '%tech%'
                          - clientRef:
                              _ilike: '%45%'
                      - active:
                          _eq: true
                      - createdAt:
                          _gte: '1900-01-01T00:00:00Z'
                      - partnerStaffId:
                          _in:
                            - 5
                            - 6
                            - 7
                            - 8
                orderBy:
                  type: array
                  description: Dynamic ordering specifications with multiple fields
                  items:
                    type: object
                  example:
                    - name: asc
                    - createdAt: desc
            examples:
              default_search:
                summary: Default search with filtering
                value:
                  limit: 1
                  where:
                    _and:
                      - _or:
                          - name:
                              _ilike: '%tech%'
                          - clientRef:
                              _ilike: '%45%'
                      - active:
                          _eq: true
                      - createdAt:
                          _gte: '1900-01-01T00:00:00Z'
                      - partnerStaffId:
                          _in:
                            - 5
                            - 6
                            - 7
                            - 8
                  orderBy:
                    - name: asc
                    - createdAt: desc
      responses:
        '200':
          description: Successfully retrieved filtered clients with dynamic ordering
          content:
            application/json:
              schema:
                type: object
                properties:
                  clients:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Unique client identifier
                          example: 3001
                        pmsRef:
                          type: string
                          description: Practice management system reference
                          example: '1650'
                        clientRef:
                          type: string
                          description: Client reference number
                          example: '48250'
                        name:
                          type: string
                          description: Client name or company name
                          example: TechFlow Enterprises
                        clientKey:
                          type: string
                          description: Client key identifier
                          example: 000000048250                              f
                        active:
                          type: boolean
                          description: Client active status
                          example: true
                        partnerStaffId:
                          type: integer
                          description: Partner staff member assigned to client
                          example: 6
                        managerStaffId:
                          type: integer
                          description: Manager staff member assigned to client
                          example: 25
                        createdAt:
                          type: string
                          format: date-time
                          description: Client record creation timestamp
                          example: '2024-05-12T22:43:57.189235+00:00'
                        updatedAt:
                          type: string
                          format: date-time
                          description: Client record last update timestamp
                          example: '2024-05-12T22:43:57.189235+00:00'
                        clientContactInfo:
                          type: object
                          nullable: true
                          description: Client contact information
                          properties:
                            id:
                              type: integer
                              example: 2850
                            firstName:
                              type: string
                              nullable: true
                              example: Jennifer
                            lastName:
                              type: string
                              nullable: true
                              example: Martinez
                            email:
                              type: string
                              nullable: true
                              example: jennifer@techflow.com
                            phone:
                              type: string
                              nullable: true
                              example: 555-0123
                            address:
                              type: string
                              nullable: true
                              example: 123 Business Plaza
                            city:
                              type: string
                              nullable: true
                              example: San Francisco
                            state:
                              type: string
                              nullable: true
                              example: CA
                            zip_code:
                              type: string
                              nullable: true
                              example: '94105'
                        partnerStaff:
                          type: object
                          description: Partner staff member details
                          properties:
                            id:
                              type: integer
                              example: 6
                            firstName:
                              type: string
                              example: Robert
                            lastName:
                              type: string
                              example: Chen
                            email:
                              type: string
                              example: robert.chen@company.com
                        managerStaff:
                          type: object
                          description: Manager staff member details
                          properties:
                            id:
                              type: integer
                              example: 25
                            firstName:
                              type: string
                              example: Sarah
                            lastName:
                              type: string
                              example: Johnson
                            email:
                              type: string
                              example: sarah.johnson@company.com
                  total:
                    type: object
                    properties:
                      aggregate:
                        type: object
                        properties:
                          count:
                            type: integer
                            description: Total number of clients matching filter criteria
                            example: 59
              examples:
                successful_response:
                  summary: Filtered clients with dynamic ordering and relationships
                  value:
                    clients:
                      - id: 3001
                        pmsRef: '1650'
                        clientRef: '48250'
                        name: TechFlow Enterprises
                        clientKey: 000000048250                              f
                        active: true
                        partnerStaffId: 6
                        managerStaffId: 25
                        createdAt: '2024-05-12T22:43:57.189235+00:00'
                        updatedAt: '2024-05-12T22:43:57.189235+00:00'
                        clientContactInfo:
                          id: 2850
                          firstName: Jennifer
                          lastName: Martinez
                          email: jennifer@techflow.com
                          phone: 555-0123
                          address: 123 Business Plaza
                          city: San Francisco
                          state: CA
                          zip_code: '94105'
                        partnerStaff:
                          id: 6
                          firstName: Robert
                          lastName: Chen
                          email: robert.chen@company.com
                        managerStaff:
                          id: 25
                          firstName: Sarah
                          lastName: Johnson
                          email: sarah.johnson@company.com
                      - id: 3002
                        pmsRef: '1651'
                        clientRef: '48251'
                        name: DataSolutions Corp
                        clientKey: 000000048251                              f
                        active: true
                        partnerStaffId: 7
                        managerStaffId: 26
                        createdAt: '2024-05-11T15:22:45.123456+00:00'
                        updatedAt: '2024-05-11T15:22:45.123456+00:00'
                        clientContactInfo:
                          id: 2851
                          firstName: Michael
                          lastName: Davis
                          email: michael@datasolutions.com
                          phone: 555-0124
                          address: 456 Tech Center
                          city: Austin
                          state: TX
                          zip_code: '73301'
                        partnerStaff:
                          id: 7
                          firstName: Lisa
                          lastName: Wong
                          email: lisa.wong@company.com
                        managerStaff:
                          id: 26
                          firstName: David
                          lastName: Thompson
                          email: david.thompson@company.com
                    total:
                      aggregate:
                        count: 59
                real_api_response:
                  summary: Sample from actual API response
                  value:
                    clients:
                      - id: 2576
                        pmsRef: '1403'
                        clientRef: '45985'
                        name: Adan Kozey
                        clientKey: 000000045985                              f
                        active: true
                        partnerStaffId: 6
                        managerStaffId: 25
                        createdAt: '2023-05-12T22:43:57.189235+00:00'
                        updatedAt: '2023-05-12T22:43:57.189235+00:00'
                        clientContactInfo:
                          id: 2622
                          firstName: null
                          lastName: null
                          email: null
                          phone: null
                          address: 995 Arron Lights
                          city: New Corrine
                          state: MT
                          zip_code: '71951'
                        partnerStaff:
                          id: 6
                          firstName: Erline
                          lastName: Ruecker
                          email: joel.walker@hotmail.com
                        managerStaff:
                          id: 25
                          firstName: Ada
                          lastName: Kovacek
                          email: norbert.ruecker@yahoo.com
                    total:
                      aggregate:
                        count: 59
                empty_response:
                  summary: No clients match filter criteria
                  value:
                    clients: []
                    total:
                      aggregate:
                        count: 0
        '400':
          description: Bad request - invalid filter parameters or malformed where clause
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              examples:
                invalid_where_clause:
                  summary: Malformed where clause
                  value:
                    error: >-
                      Invalid where clause structure: missing operator in
                      condition
                    code: INVALID_WHERE_CLAUSE
                invalid_order_by:
                  summary: Invalid ordering specification
                  value:
                    error: Invalid orderBy field or direction specified
                    code: INVALID_ORDER_BY
        '401':
          description: Unauthorized - missing or invalid admin secret
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              examples:
                missing_auth:
                  summary: Missing authentication header
                  value:
                    error: x-hasura-admin-secret header is required
                    code: MISSING_AUTH_HEADER
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
  /gql/v1/client/{id}:
    get:
      tags:
        - Client
      summary: Get client by ID
      description: |
        **Retrieve a specific client by its unique identifier**

        This endpoint provides detailed client information including:
        - Complete client details and demographics
        - Client status and relationship information
        - Contact and address information
        - Engagement and project portfolio
        - Financial and billing information
        - Industry and business classification

        **Client Management Features:**
        - Client lifecycle tracking
        - Relationship management
        - Contact and address management
        - Engagement portfolio oversight
        - Financial and billing setup

        **Client Details Include:**
        - Client name and demographics
        - Client status and type
        - Contact information
        - Address and location
        - Engagement portfolio
        - Financial information

        **Business Applications:**
        - Client relationship management
        - Engagement portfolio analysis
        - Financial performance tracking
        - Contact management
        - Business development planning

        **Real Example:**
        ```bash
        curl --location 'https://{{host}}/v1/client/789' \
        --header 'Authorization: bearer {{token}}' \
        --header 'Content-Type: application/json'
        ```

        **Response Example:**
        ```json
        {
          "id": 789,
          "name": "Acme Corporation",
          "legalName": "Acme Corporation, Inc.",
          "status": "ACTIVE",
          "type": "CORPORATE",
          "industry": "MANUFACTURING",
          "size": "LARGE",
          "website": "https://www.acme.com",
          "taxId": "12-3456789",
          "phone": "+1-555-0123",
          "email": "info@acme.com",
          "address": {
            "street": "123 Business Ave",
            "city": "New York",
            "state": "NY",
            "zipCode": "10001",
            "country": "USA"
          },
          "billingAddress": {
            "street": "456 Finance Blvd",
            "city": "New York",
            "state": "NY",
            "zipCode": "10002",
            "country": "USA"
          },
          "primaryContact": {
            "id": 23456,
            "name": "John Smith",
            "title": "Chief Financial Officer",
            "email": "john.smith@acme.com",
            "phone": "+1-555-0123"
          },
          "engagements": [
            {
              "id": 34567,
              "name": "Annual Audit Engagement 2024",
              "status": "ACTIVE",
              "type": "AUDIT",
              "startDate": "2024-01-01T00:00:00Z",
              "endDate": "2024-12-31T23:59:59Z"
            }
          ],
          "financialSummary": {
            "totalRevenue": 150000.00,
            "outstandingBalance": 25000.00,
            "currency": "USD",
            "lastPaymentDate": "2024-11-15T10:30:00Z"
          },
          "notes": "Long-term client with excellent payment history and strong relationship",
          "createdAt": "2020-01-15T10:00:00Z",
          "updatedAt": "2024-11-20T14:30:00Z"
        }
        ```
      operationId: getClientById
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier of the client
          schema:
            type: integer
            minimum: 1
          example: 789
      responses:
        '200':
          description: Client details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: Unique client identifier
                    example: 789
                  name:
                    type: string
                    description: Client name
                    example: Acme Corporation
                  legalName:
                    type: string
                    description: Legal business name
                    example: Acme Corporation, Inc.
                  status:
                    type: string
                    description: Client status
                    enum:
                      - ACTIVE
                      - INACTIVE
                      - PROSPECT
                      - FORMER
                    example: ACTIVE
                  type:
                    type: string
                    description: Client type
                    enum:
                      - CORPORATE
                      - INDIVIDUAL
                      - PARTNERSHIP
                      - LLC
                      - NONPROFIT
                    example: CORPORATE
                  industry:
                    type: string
                    description: Industry classification
                    enum:
                      - MANUFACTURING
                      - RETAIL
                      - HEALTHCARE
                      - FINANCIAL
                      - TECHNOLOGY
                      - CONSULTING
                      - OTHER
                    example: MANUFACTURING
                  size:
                    type: string
                    description: Company size classification
                    enum:
                      - SMALL
                      - MEDIUM
                      - LARGE
                      - ENTERPRISE
                    example: LARGE
                  website:
                    type: string
                    format: uri
                    description: Company website URL
                    example: https://www.acme.com
                  taxId:
                    type: string
                    description: Tax identification number
                    example: 12-3456789
                  phone:
                    type: string
                    description: Primary phone number
                    example: +1-555-0123
                  email:
                    type: string
                    format: email
                    description: Primary email address
                    example: info@acme.com
                  address:
                    type: object
                    description: Primary business address
                    properties:
                      street:
                        type: string
                        description: Street address
                        example: 123 Business Ave
                      city:
                        type: string
                        description: City
                        example: New York
                      state:
                        type: string
                        description: State or province
                        example: NY
                      zipCode:
                        type: string
                        description: ZIP or postal code
                        example: '10001'
                      country:
                        type: string
                        description: Country
                        example: USA
                  billingAddress:
                    type: object
                    description: Billing address (if different from primary)
                    properties:
                      street:
                        type: string
                        description: Street address
                        example: 456 Finance Blvd
                      city:
                        type: string
                        description: City
                        example: New York
                      state:
                        type: string
                        description: State or province
                        example: NY
                      zipCode:
                        type: string
                        description: ZIP or postal code
                        example: '10002'
                      country:
                        type: string
                        description: Country
                        example: USA
                  primaryContact:
                    type: object
                    description: Primary contact information
                    properties:
                      id:
                        type: integer
                        description: Contact identifier
                        example: 23456
                      name:
                        type: string
                        description: Contact name
                        example: John Smith
                      title:
                        type: string
                        description: Contact title
                        example: Chief Financial Officer
                      email:
                        type: string
                        format: email
                        description: Contact email
                        example: john.smith@acme.com
                      phone:
                        type: string
                        description: Contact phone
                        example: +1-555-0123
                  engagements:
                    type: array
                    description: Active engagements for this client
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Engagement identifier
                          example: 34567
                        name:
                          type: string
                          description: Engagement name
                          example: Annual Audit Engagement 2024
                        status:
                          type: string
                          description: Engagement status
                          enum:
                            - PLANNING
                            - ACTIVE
                            - ON_HOLD
                            - COMPLETED
                            - CANCELLED
                          example: ACTIVE
                        type:
                          type: string
                          description: Engagement type
                          enum:
                            - AUDIT
                            - REVIEW
                            - COMPILATION
                            - TAX
                            - CONSULTING
                            - ADVISORY
                          example: AUDIT
                        startDate:
                          type: string
                          format: date-time
                          description: Engagement start date
                          example: '2024-01-01T00:00:00Z'
                        endDate:
                          type: string
                          format: date-time
                          description: Engagement end date
                          example: '2024-12-31T23:59:59Z'
                  financialSummary:
                    type: object
                    description: Financial summary for this client
                    properties:
                      totalRevenue:
                        type: number
                        format: decimal
                        description: Total revenue from this client
                        example: 150000
                      outstandingBalance:
                        type: number
                        format: decimal
                        description: Outstanding balance owed
                        example: 25000
                      currency:
                        type: string
                        description: Currency code
                        example: USD
                      lastPaymentDate:
                        type: string
                        format: date-time
                        description: Date of last payment
                        example: '2024-11-15T10:30:00Z'
                  notes:
                    type: string
                    description: Additional notes about the client
                    example: >-
                      Long-term client with excellent payment history and strong
                      relationship
                  createdAt:
                    type: string
                    format: date-time
                    description: Client creation timestamp
                    example: '2020-01-15T10:00:00Z'
                  updatedAt:
                    type: string
                    format: date-time
                    description: Last update timestamp
                    example: '2024-11-20T14:30:00Z'
        '401':
          description: Unauthorized - Invalid or missing authentication token
        '403':
          description: Forbidden - Insufficient permissions to access this client
        '404':
          description: Client not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Client not found
                  message:
                    type: string
                    example: Client with ID 789 does not exist
        '500':
          description: Internal server error
  /gql/v1/contacts:
    post:
      tags:
        - Contact
      summary: List contacts
      description: >
        **Retrieve all contacts with basic pagination support**


        Returns a paginated list of contacts. Default sort prioritizes
        last/first name.


        Real Example:

        ```bash

        curl --location 'https://{{host}}/v1/contacts' \

        --header 'Authorization: bearer {{token}}' \

        --header 'Content-Type: application/json' \

        --data '{
          "pageSize": 25,
          "page": 0
        }'

        ```
      operationId: getContactsPaginated
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                pageSize:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 50
                  description: Maximum number of contacts to return
                page:
                  type: integer
                  minimum: 0
                  default: 0
                  description: Number of records to skip for pagination
            examples:
              default_pagination:
                summary: Default pagination
                value:
                  pageSize: 25
                  page: 0
      responses:
        '200':
          description: Successfully retrieved contacts
        '400':
          description: Bad request - invalid pagination parameters
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /gql/v1/contacts/search:
    post:
      tags:
        - Contact
      summary: Search contacts
      description: >
        **Advanced contact filtering with custom GraphQL where clauses and
        dynamic ordering**


        Filter contacts using boolean logic and relationship-aware fields from
        `contact_info`.


        Real Example:

        ```bash

        curl --location 'https://{{host}}/v1/contacts/search' \

        --header 'Authorization: bearer {{token}}' \

        --header 'Content-Type: application/json' \

        --data '{
          "pageSize": 1,
          "where": {
            "_and": [
              {
                "_or": [
                  {
                    "contact_info": {
                      "firstName": {
                        "_ilike": "%john%"
                      }
                    }
                  },
                  {
                    "contact_info": {
                      "lastName": {
                        "_ilike": "%doe%"
                      }
                    }
                  }
                ]
              },
              {
                "active": {
                  "_eq": true
                }
              },
              {
                "createdAt": {
                  "_gte": "1900-01-01T00:00:00Z"
                }
              },
              {
                "contact_info": {
                  "email": {
                    "_ilike": "%@company.com%"
                  }
                }
              }
            ]
          },
          "orderBy": [
            {
              "contact_info": {
                "lastName": "asc"
              }
            },
            {
              "createdAt": "desc"
            }
          ]
        }'

        ```
      operationId: filterContactsDynamic
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                limit:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 1
                where:
                  type: object
                  description: GraphQL-style where clause for complex contact filtering
                  example:
                    _and:
                      - _or:
                          - contact_info:
                              firstName:
                                _ilike: '%john%'
                          - contact_info:
                              lastName:
                                _ilike: '%doe%'
                      - active:
                          _eq: true
                      - createdAt:
                          _gte: '1900-01-01T00:00:00Z'
                      - contact_info:
                          email:
                            _ilike: '%@company.com%'
                orderBy:
                  type: array
                  items:
                    type: object
                  description: Dynamic ordering with nested relationship fields
                  example:
                    - contact_info:
                        lastName: asc
                    - createdAt: desc
      responses:
        '200':
          description: Successfully retrieved filtered contacts
        '400':
          description: Bad request - invalid where/orderBy
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /gql/v1/contact/{id}:
    get:
      tags:
        - Contact
      summary: Get contact by ID
      description: |
        **Retrieve a specific contact by its unique identifier**

        This endpoint provides detailed contact information including:
        - Complete contact details and demographics
        - Contact status and relationship information
        - Client associations and roles
        - Communication preferences and history
        - Address and location information
        - Professional and personal details

        **Contact Management Features:**
        - Contact lifecycle tracking
        - Client relationship management
        - Communication preference management
        - Address and location tracking
        - Professional information management

        **Contact Details Include:**
        - Contact name and demographics
        - Contact status and type
        - Client associations
        - Communication preferences
        - Address information
        - Professional details

        **Business Applications:**
        - Contact relationship management
        - Client communication planning
        - Contact database maintenance
        - Professional network management
        - Communication preference tracking

        **Real Example:**
        ```bash
        curl --location 'https://{{host}}/v1/contact/23456' \
        --header 'Authorization: bearer {{token}}' \
        --header 'Content-Type: application/json'
        ```

        **Response Example:**
        ```json
        {
          "id": 23456,
          "firstName": "John",
          "lastName": "Smith",
          "email": "john.smith@acme.com",
          "phone": "+1-555-0123",
          "mobile": "+1-555-0456",
          "title": "Chief Financial Officer",
          "department": "Finance",
          "status": "ACTIVE",
          "type": "CLIENT_CONTACT",
          "clientId": 789,
          "clientName": "Acme Corporation",
          "isPrimaryContact": true,
          "address": {
            "street": "123 Business Ave",
            "city": "New York",
            "state": "NY",
            "zipCode": "10001",
            "country": "USA"
          },
          "communicationPreferences": {
            "preferredMethod": "EMAIL",
            "emailFrequency": "WEEKLY",
            "newsletterSubscription": true,
            "marketingEmails": false
          },
          "notes": "Primary contact for all financial matters and audit communications",
          "createdAt": "2023-01-15T10:00:00Z",
          "updatedAt": "2024-11-20T14:30:00Z"
        }
        ```
      operationId: getContactById
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier of the contact
          schema:
            type: integer
            minimum: 1
          example: 23456
      responses:
        '200':
          description: Contact details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: Unique contact identifier
                    example: 23456
                  firstName:
                    type: string
                    description: Contact first name
                    example: John
                  lastName:
                    type: string
                    description: Contact last name
                    example: Smith
                  email:
                    type: string
                    format: email
                    description: Primary email address
                    example: john.smith@acme.com
                  phone:
                    type: string
                    description: Primary phone number
                    example: +1-555-0123
                  mobile:
                    type: string
                    description: Mobile phone number
                    example: +1-555-0456
                  title:
                    type: string
                    description: Job title or position
                    example: Chief Financial Officer
                  department:
                    type: string
                    description: Department or division
                    example: Finance
                  status:
                    type: string
                    description: Contact status
                    enum:
                      - ACTIVE
                      - INACTIVE
                      - PENDING
                      - BLOCKED
                    example: ACTIVE
                  type:
                    type: string
                    description: Contact type
                    enum:
                      - CLIENT_CONTACT
                      - PROSPECT
                      - VENDOR
                      - PARTNER
                      - STAFF
                    example: CLIENT_CONTACT
                  clientId:
                    type: integer
                    description: Associated client identifier
                    example: 789
                  clientName:
                    type: string
                    description: Client name
                    example: Acme Corporation
                  isPrimaryContact:
                    type: boolean
                    description: Whether this is the primary contact for the client
                    example: true
                  address:
                    type: object
                    description: Contact address information
                    properties:
                      street:
                        type: string
                        description: Street address
                        example: 123 Business Ave
                      city:
                        type: string
                        description: City
                        example: New York
                      state:
                        type: string
                        description: State or province
                        example: NY
                      zipCode:
                        type: string
                        description: ZIP or postal code
                        example: '10001'
                      country:
                        type: string
                        description: Country
                        example: USA
                  communicationPreferences:
                    type: object
                    description: Communication preferences
                    properties:
                      preferredMethod:
                        type: string
                        description: Preferred communication method
                        enum:
                          - EMAIL
                          - PHONE
                          - SMS
                          - MAIL
                        example: EMAIL
                      emailFrequency:
                        type: string
                        description: Preferred email frequency
                        enum:
                          - DAILY
                          - WEEKLY
                          - MONTHLY
                          - QUARTERLY
                          - NEVER
                        example: WEEKLY
                      newsletterSubscription:
                        type: boolean
                        description: Whether subscribed to newsletters
                        example: true
                      marketingEmails:
                        type: boolean
                        description: Whether accepts marketing emails
                        example: false
                  notes:
                    type: string
                    description: Additional notes about the contact
                    example: >-
                      Primary contact for all financial matters and audit
                      communications
                  createdAt:
                    type: string
                    format: date-time
                    description: Contact creation timestamp
                    example: '2023-01-15T10:00:00Z'
                  updatedAt:
                    type: string
                    format: date-time
                    description: Last update timestamp
                    example: '2024-11-20T14:30:00Z'
        '401':
          description: Unauthorized - Invalid or missing authentication token
        '403':
          description: Forbidden - Insufficient permissions to access this contact
        '404':
          description: Contact not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Contact not found
                  message:
                    type: string
                    example: Contact with ID 23456 does not exist
        '500':
          description: Internal server error
  /gql/v1/engagements:
    post:
      tags:
        - Engagement
      summary: List engagements
      description: >
        **Project engagement tracking with comprehensive workflow management**


        This endpoint delivers complete project engagement management including:

        - Client engagement tracking with date-based filtering

        - Multi-level staff assignment management (partner and manager roles)

        - Project status workflow tracking and reporting

        - Template-driven engagement naming and standardization

        - Date range analysis for project timeline management


        **Project Management Capabilities:**

        - Start and end date tracking for project lifecycles

        - Status-based workflow management (ACTIVE, COMPLETED, ON_HOLD,
        EXECUTED, etc.)

        - Staff assignment tracking at partner and manager levels

        - Client relationship management for engagement context


        **Workflow Features:**

        - Template-based engagement creation for consistency

        - Status progression tracking for project milestones

        - Staff allocation and responsibility assignment

        - Client-specific engagement history and analysis


        **Business Intelligence:**

        - Engagement duration analysis and reporting

        - Staff utilization and assignment tracking

        - Client engagement patterns and history

        - Project status distribution and workflow analysis


        **Filtering and Analysis:**

        - Client-specific engagement retrieval

        - Status-based workflow filtering

        - Date range queries for period analysis

        - Staff assignment reporting and allocation


        **Real Example:**

        ```bash

        curl --location 'https://{{host}}/v1/engagements' \

        --header 'Authorization: bearer {{token}} \

        --header 'Content-Type: application/json' \

        --data '{
          "pageSize": 25,
          "page": 0
        }'

        ```
      operationId: getEngagements
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                pageSize:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 25
                  description: Maximum number of engagement records to return
                  example: 25
                page:
                  type: integer
                  minimum: 0
                  default: 0
                  description: Page number for pagination (0-based)
                  example: 0
                clientId:
                  type: integer
                  description: Filter engagements by specific client ID
                  example: 420
                status:
                  type: string
                  description: Filter by engagement status
                  enum:
                    - ACTIVE
                    - COMPLETED
                    - ON_HOLD
                    - EXECUTED
                    - CANCELLED
                    - PLANNED
                  example: EXECUTED
                startDate:
                  type: string
                  format: date
                  description: Start date for engagement date range filter
                  example: '2023-06-29'
                endDate:
                  type: string
                  format: date
                  description: End date for engagement date range filter
                  example: '2023-06-29'
                sortOrder:
                  type: string
                  enum:
                    - asc
                    - desc
                  default: desc
                  description: Sort order for engagement dates
                  example: desc
            examples:
              default_pagination:
                summary: Default pagination
                value:
                  pageSize: 25
                  page: 0
      responses:
        '200':
          description: Successfully retrieved engagement records
          content:
            application/json:
              schema:
                type: object
                properties:
                  deid_engagement:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Unique engagement identifier
                          example: 8
                        name:
                          type: string
                          description: Generated engagement name from template
                          example: 2024 Annual Review and Tax 52150
                        start_dt:
                          type: string
                          format: date
                          description: Engagement start date
                          example: '2024-03-15'
                        end_dt:
                          type: string
                          format: date
                          description: Engagement end date
                          example: '2024-04-30'
                        status:
                          type: string
                          description: Current engagement status
                          example: EXECUTED
                        client_id:
                          type: integer
                          description: Associated client identifier
                          example: 420
                        partner_staff_id:
                          type: integer
                          description: Partner staff member assigned to engagement
                          example: 53
                        manager_staff_id:
                          type: integer
                          description: Manager staff member assigned to engagement
                          example: 15
                        created_at:
                          type: string
                          format: date-time
                          description: Engagement record creation timestamp
                          example: '2024-03-14T10:58:38.605333+00:00'
                        updated_at:
                          type: string
                          format: date-time
                          description: Engagement record last update timestamp
                          example: '2024-07-27T00:08:05.822177+00:00'
                        engagement_name_template:
                          type: string
                          description: Template used to generate engagement name
                          example: >-
                            {{fiscal_year.year}} {{letter_template.name}}
                            {{client.number}}
                        client:
                          type: object
                          nullable: true
                          description: Associated client details
                          properties:
                            id:
                              type: integer
                              example: 420
                            name:
                              type: string
                              example: TechFlow Enterprises
                            number:
                              type: string
                              example: '52150'
                        partnerStaff:
                          type: object
                          nullable: true
                          description: Partner staff member details
                          properties:
                            id:
                              type: integer
                              example: 53
                            firstName:
                              type: string
                              example: Robert
                            lastName:
                              type: string
                              example: Johnson
                            email:
                              type: string
                              example: r.johnson@company.com
                        managerStaff:
                          type: object
                          nullable: true
                          description: Manager staff member details
                          properties:
                            id:
                              type: integer
                              example: 15
                            firstName:
                              type: string
                              example: Sarah
                            lastName:
                              type: string
                              example: Martinez
                            email:
                              type: string
                              example: s.martinez@company.com
                  deid_engagement_aggregate:
                    type: object
                    properties:
                      aggregate:
                        type: object
                        properties:
                          count:
                            type: integer
                            description: >-
                              Total number of engagement records matching
                              criteria
                            example: 1
              examples:
                successful_response:
                  summary: Engagement records with staff and client details
                  value:
                    deid_engagement:
                      - id: 8
                        name: 2024 Annual Review and Tax 52150
                        start_dt: '2024-03-15'
                        end_dt: '2024-04-30'
                        status: EXECUTED
                        client_id: 420
                        partner_staff_id: 53
                        manager_staff_id: 15
                        created_at: '2024-03-14T10:58:38.605333+00:00'
                        updated_at: '2024-07-27T00:08:05.822177+00:00'
                        engagement_name_template: >-
                          {{fiscal_year.year}} {{letter_template.name}}
                          {{client.number}}
                        client:
                          id: 420
                          name: TechFlow Enterprises
                          number: '52150'
                        partnerStaff:
                          id: 53
                          firstName: Robert
                          lastName: Johnson
                          email: r.johnson@company.com
                        managerStaff:
                          id: 15
                          firstName: Sarah
                          lastName: Martinez
                          email: s.martinez@company.com
                      - id: 9
                        name: 2024 Quarterly Review 52150
                        start_dt: '2024-07-01'
                        end_dt: '2024-07-15'
                        status: ACTIVE
                        client_id: 420
                        partner_staff_id: 53
                        manager_staff_id: 22
                        created_at: '2024-06-28T09:30:15.123456+00:00'
                        updated_at: '2024-07-01T14:22:30.789012+00:00'
                        engagement_name_template: >-
                          {{fiscal_year.year}} {{service_type.name}}
                          {{client.number}}
                        client:
                          id: 420
                          name: TechFlow Enterprises
                          number: '52150'
                        partnerStaff:
                          id: 53
                          firstName: Robert
                          lastName: Johnson
                          email: r.johnson@company.com
                        managerStaff:
                          id: 22
                          firstName: David
                          lastName: Chen
                          email: d.chen@company.com
                    deid_engagement_aggregate:
                      aggregate:
                        count: 2
                single_engagement:
                  summary: Single engagement from real API response
                  value:
                    deid_engagement:
                      - id: 7
                        name: 2025 NFP Review and Tax 51840
                        start_dt: '2023-06-29'
                        end_dt: '2023-06-29'
                        status: EXECUTED
                        client_id: 420
                        partner_staff_id: 53
                        manager_staff_id: 15
                        created_at: '2025-03-14T10:58:38.605333+00:00'
                        updated_at: '2025-07-27T00:08:05.822177+00:00'
                        engagement_name_template: >-
                          {{fiscal_year.year}} {{letter_template.name}}
                          {{client.number}}
                    deid_engagement_aggregate:
                      aggregate:
                        count: 1
                empty_response:
                  summary: No engagements found
                  value:
                    deid_engagement: []
                    deid_engagement_aggregate:
                      aggregate:
                        count: 0
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              examples:
                invalid_date_range:
                  summary: Invalid date range
                  value:
                    error: startDate must be before or equal to endDate
                    code: INVALID_DATE_RANGE
                invalid_client_id:
                  summary: Invalid client ID
                  value:
                    error: clientId must be a positive integer
                    code: INVALID_CLIENT_ID
        '401':
          description: Unauthorized - missing or invalid admin secret
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              examples:
                missing_auth:
                  summary: Missing authentication header
                  value:
                    error: x-hasura-admin-secret header is required
                    code: MISSING_AUTH_HEADER
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
  /gql/v1/engagements/search:
    post:
      tags:
        - Engagement
      summary: Search engagements
      description: >
        **Search Engagements with Dynamic Filters**


        This endpoint allows you to search engagements using dynamic filters,
        enabling flexible querying based on various criteria.


        **Features:**

        - Supports multiple filter conditions

        - Pagination for large result sets

        - Sorting options for results


        **Example Usage:**

        ```bash

        curl --location 'https://{{host}}/v1/engagements/search' \

        --data '{
          "pageSize": 1,
          "where": {
            "_and": [
              {
                "_or": [
                  {
                    "name": {
                      "_ilike": "%review%"
                    }
                  },
                  {
                    "engagementNameTemplate": {
                      "_ilike": "%tax%"
                    }
                  }
                ]
              },
              {
                "status": {
                  "_in": ["ACTIVE", "EXECUTED"]
                }
              },
              {
                "createdAt": {
                  "_gte": "1900-01-01T00:00:00Z"
                }
              },
              {
                "partnerStaffId": {
                  "_in": [
                    5,
                    6,
                    7,
                    8
                  ]
                }
              }
            ]
          },
          "orderBy": [
            {
              "name": "asc"
            },
            {
              "createdAt": "desc"
            }
          ]
        }'

        ```
      operationId: searchEngagementsDynamic
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                limit:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 1
                  description: Maximum number of engagements to return
                  example: 1
                where:
                  type: object
                  description: GraphQL-style where clause for complex filtering
                  example:
                    _and:
                      - _or:
                          - name:
                              _ilike: '%review%'
                          - engagementNameTemplate:
                              _ilike: '%tax%'
                      - status:
                          _in:
                            - ACTIVE
                            - EXECUTED
                      - createdAt:
                          _gte: '1900-01-01T00:00:00Z'
                      - partnerStaffId:
                          _in:
                            - 5
                            - 6
                            - 7
                            - 8
                orderBy:
                  type: array
                  items:
                    type: object
                  description: Dynamic ordering specifications
                  example:
                    - name: asc
                    - createdAt: desc
            examples:
              default_search:
                summary: Default search with filtering
                value:
                  limit: 1
                  where:
                    _and:
                      - _or:
                          - name:
                              _ilike: '%review%'
                          - engagementNameTemplate:
                              _ilike: '%tax%'
                      - status:
                          _in:
                            - ACTIVE
                            - EXECUTED
                      - createdAt:
                          _gte: '1900-01-01T00:00:00Z'
                      - partnerStaffId:
                          _in:
                            - 5
                            - 6
                            - 7
                            - 8
                  orderBy:
                    - name: asc
                    - createdAt: desc
      responses:
        '200':
          description: Engagements retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  engagements:
                    type: array
                    items:
                      $ref: '#/components/schemas/Engagement'
                  totalCount:
                    type: integer
                    description: Total number of engagements matching the filters
                    example: 100
        '400':
          description: Bad Request - Invalid input parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error - An unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /gql/v1/engagement/{id}:
    get:
      tags:
        - Engagement
      summary: Get engagement by ID
      description: |
        **Retrieve a specific engagement by its unique identifier**

        This endpoint provides detailed engagement information including:
        - Complete engagement details and scope
        - Engagement status and lifecycle information
        - Client relationship and contact details
        - Project portfolio and deliverables
        - Team assignments and resource allocation
        - Financial terms and billing arrangements

        **Engagement Management Features:**
        - Engagement lifecycle tracking
        - Client relationship management
        - Project portfolio oversight
        - Team resource allocation
        - Financial terms and billing setup

        **Engagement Details Include:**
        - Engagement name and description
        - Engagement status and type
        - Client and contact information
        - Project portfolio details
        - Team assignments
        - Financial terms and billing

        **Business Applications:**
        - Engagement status monitoring
        - Client relationship management
        - Project portfolio analysis
        - Resource allocation planning
        - Financial performance tracking

        **Real Example:**
        ```bash
        curl --location 'https://{{host}}/v1/engagement/34567' \
        --header 'Authorization: bearer {{token}}' \
        --header 'Content-Type: application/json'
        ```

        **Response Example:**
        ```json
        {
          "id": 34567,
          "name": "Annual Audit Engagement 2024",
          "description": "Comprehensive annual audit engagement including financial statements, tax preparation, and compliance review",
          "status": "ACTIVE",
          "type": "AUDIT",
          "clientId": 789,
          "clientName": "Acme Corporation",
          "clientEmail": "finance@acme.com",
          "clientPhone": "+1-555-0123",
          "startDate": "2024-01-01T00:00:00Z",
          "endDate": "2024-12-31T23:59:59Z",
          "estimatedValue": 50000.00,
          "currency": "USD",
          "projects": [
            {
              "id": 67890,
              "name": "Q4 Financial Audit",
              "status": "IN_PROGRESS",
              "budget": 25000.00
            },
            {
              "id": 67891,
              "name": "Tax Preparation",
              "status": "PLANNING",
              "budget": 15000.00
            }
          ],
          "teamMembers": [
            {
              "staffId": 123,
              "name": "John Smith",
              "role": "ENGAGEMENT_PARTNER",
              "allocation": 0.3
            },
            {
              "staffId": 124,
              "name": "Jane Doe",
              "role": "SENIOR_MANAGER",
              "allocation": 0.8
            }
          ],
          "billingTerms": {
            "billingFrequency": "MONTHLY",
            "paymentTerms": "NET_30",
            "rateType": "HOURLY",
            "defaultRate": 250.00
          },
          "notes": "Annual engagement with quarterly reviews and monthly billing",
          "createdAt": "2023-12-15T10:00:00Z",
          "updatedAt": "2024-11-20T14:30:00Z"
        }
        ```
      operationId: getEngagementById
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier of the engagement
          schema:
            type: integer
            minimum: 1
          example: 34567
      responses:
        '200':
          description: Engagement details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: Unique engagement identifier
                    example: 34567
                  name:
                    type: string
                    description: Engagement name
                    example: Annual Audit Engagement 2024
                  description:
                    type: string
                    description: Detailed engagement description
                    example: >-
                      Comprehensive annual audit engagement including financial
                      statements, tax preparation, and compliance review
                  status:
                    type: string
                    description: Engagement status
                    enum:
                      - PLANNING
                      - ACTIVE
                      - ON_HOLD
                      - COMPLETED
                      - CANCELLED
                    example: ACTIVE
                  type:
                    type: string
                    description: Engagement type
                    enum:
                      - AUDIT
                      - REVIEW
                      - COMPILATION
                      - TAX
                      - CONSULTING
                      - ADVISORY
                    example: AUDIT
                  clientId:
                    type: integer
                    description: Associated client identifier
                    example: 789
                  clientName:
                    type: string
                    description: Client name
                    example: Acme Corporation
                  clientEmail:
                    type: string
                    description: Primary client contact email
                    example: finance@acme.com
                  clientPhone:
                    type: string
                    description: Primary client contact phone
                    example: +1-555-0123
                  startDate:
                    type: string
                    format: date-time
                    description: Engagement start date
                    example: '2024-01-01T00:00:00Z'
                  endDate:
                    type: string
                    format: date-time
                    description: Engagement end date
                    example: '2024-12-31T23:59:59Z'
                  estimatedValue:
                    type: number
                    format: decimal
                    description: Estimated engagement value
                    example: 50000
                  currency:
                    type: string
                    description: Engagement currency code
                    example: USD
                  projects:
                    type: array
                    description: Projects within this engagement
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Project identifier
                          example: 67890
                        name:
                          type: string
                          description: Project name
                          example: Q4 Financial Audit
                        status:
                          type: string
                          description: Project status
                          enum:
                            - PLANNING
                            - IN_PROGRESS
                            - ON_HOLD
                            - COMPLETED
                            - CANCELLED
                          example: IN_PROGRESS
                        budget:
                          type: number
                          format: decimal
                          description: Project budget
                          example: 25000
                  teamMembers:
                    type: array
                    description: Team members assigned to the engagement
                    items:
                      type: object
                      properties:
                        staffId:
                          type: integer
                          description: Staff member identifier
                          example: 123
                        name:
                          type: string
                          description: Staff member name
                          example: John Smith
                        role:
                          type: string
                          description: Role on the engagement
                          enum:
                            - ENGAGEMENT_PARTNER
                            - SENIOR_MANAGER
                            - MANAGER
                            - SENIOR_AUDITOR
                            - AUDITOR
                            - ASSOCIATE
                          example: ENGAGEMENT_PARTNER
                        allocation:
                          type: number
                          format: decimal
                          description: Time allocation percentage (0.0 to 1.0)
                          example: 0.3
                  billingTerms:
                    type: object
                    description: Billing terms and arrangements
                    properties:
                      billingFrequency:
                        type: string
                        description: Billing frequency
                        enum:
                          - WEEKLY
                          - MONTHLY
                          - QUARTERLY
                          - UPON_COMPLETION
                        example: MONTHLY
                      paymentTerms:
                        type: string
                        description: Payment terms
                        enum:
                          - NET_15
                          - NET_30
                          - NET_45
                          - NET_60
                        example: NET_30
                      rateType:
                        type: string
                        description: Rate type
                        enum:
                          - HOURLY
                          - FIXED
                          - PERCENTAGE
                        example: HOURLY
                      defaultRate:
                        type: number
                        format: decimal
                        description: Default hourly rate
                        example: 250
                  notes:
                    type: string
                    description: Additional notes or terms
                    example: >-
                      Annual engagement with quarterly reviews and monthly
                      billing
                  createdAt:
                    type: string
                    format: date-time
                    description: Engagement creation timestamp
                    example: '2023-12-15T10:00:00Z'
                  updatedAt:
                    type: string
                    format: date-time
                    description: Last update timestamp
                    example: '2024-11-20T14:30:00Z'
        '401':
          description: Unauthorized - Invalid or missing authentication token
        '403':
          description: Forbidden - Insufficient permissions to access this engagement
        '404':
          description: Engagement not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Engagement not found
                  message:
                    type: string
                    example: Engagement with ID 34567 does not exist
        '500':
          description: Internal server error
  /gql/v1/staff:
    post:
      tags:
        - Staff
      summary: List staff
      description: >
        **Staff directory and human resource management with organizational
        structure**


        This comprehensive HR endpoint provides complete staff management
        including:

        - Employee directory with advanced search capabilities

        - Department and organizational structure integration

        - Role-based staff categorization and filtering

        - Active/inactive employee status management

        - Multi-field name search with partial matching


        **HR Management Capabilities:**

        - Complete employee directory with contact information

        - Department-based organizational structure tracking

        - Staff type and role classification system

        - Active employee status for current workforce analysis

        - Employee search across first and last names


        **Organizational Features:**

        - Department hierarchy and staff allocation

        - Role-based access and staff type categorization

        - Employee status management (active/inactive)

        - Contact information and communication data

        - Staff reference and external system integration


        **Search and Filter Options:**

        - Multi-field name search (first name, last name)

        - Department-based staff filtering

        - Active status filtering for current employees

        - Role and staff type categorization

        - Alphabetical sorting for directory listings


        **Business Applications:**

        - Employee directory and contact management

        - HR reporting and organizational analysis

        - Department staff allocation and planning

        - Employee onboarding and management workflows

        - Integration with external HR and payroll systems


        **Directory Features:**

        - Complete contact information management

        - Department and role relationship tracking

        - Staff reference system for external integration

        - Employee status and lifecycle management


        **Real Example:**

        ```bash

        curl --location 'https://{{host}}/v1/staff' \

        --data '{
          "pageSize": 25,
          "page": 0
        }'

        ```


        **Permissions:**
      operationId: getStaff
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                pageSize:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 25
                  description: Maximum number of staff records to return
                  example: 25
                page:
                  type: integer
                  minimum: 0
                  default: 0
                  description: Page number for pagination (0-based)
                  example: 0
                isActive:
                  type: boolean
                  description: Filter by active employee status
                  example: true
                departmentId:
                  type: integer
                  description: Filter staff by specific department ID
                  example: 7
                nameSearch:
                  type: string
                  description: Search term for first and last names (use % for wildcard)
                  example: '%'
                sortOrder:
                  type: string
                  enum:
                    - asc
                    - desc
                  default: asc
                  description: Sort order for staff names
                  example: asc
            examples:
              default_pagination:
                summary: Default pagination
                value:
                  pageSize: 25
                  page: 0
      responses:
        '200':
          description: Successfully retrieved staff records
          content:
            application/json:
              schema:
                type: object
                properties:
                  deid_staff:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Unique staff identifier
                          example: 202
                        pmsRef:
                          type: string
                          description: PMS reference identifier
                          example: '2254'
                        firstName:
                          type: string
                          description: Staff member first name
                          example: Holley
                        lastName:
                          type: string
                          description: Staff member last name
                          example: Abbott
                        email:
                          type: string
                          format: email
                          description: Primary email address
                          example: ena.toy@hotmail.com
                        active:
                          type: boolean
                          description: Whether the staff member is active
                          example: true
                        deptId:
                          type: integer
                          description: Department identifier
                          example: 8
                        jobTitle:
                          type: string
                          nullable: true
                          description: Job title of the staff member
                          example: null
                        type:
                          type: string
                          nullable: true
                          description: Staff member type or category
                          example: null
                        officeId:
                          type: integer
                          description: Office identifier where the staff member is based
                          example: 2
                        staffManagerId:
                          type: integer
                          nullable: true
                          description: Identifier of the staff member's manager
                          example: null
                  deid_staff_aggregate:
                    type: object
                    properties:
                      aggregate:
                        type: object
                        properties:
                          count:
                            type: integer
                            description: Total number of staff records matching criteria
                            example: 138
              examples:
                successful_response:
                  summary: Staff directory with department and type information
                  value:
                    deid_staff:
                      - id: 202
                        pmsRef: '2254'
                        firstName: Holley
                        lastName: Abbott
                        email: ena.toy@hotmail.com
                        active: true
                        deptId: 8
                        jobTitle: null
                        type: null
                        officeId: 2
                        staffManagerId: null
                      - id: 203
                        pmsRef: '2255'
                        firstName: Michael
                        lastName: Chen
                        email: michael.chen@company.com
                        active: true
                        deptId: 7
                        jobTitle: Senior Developer
                        type: Full-time
                        officeId: 1
                        staffManagerId: 202
                      - id: 204
                        pmsRef: '2256'
                        firstName: Lisa
                        lastName: Martinez
                        email: lisa.martinez@company.com
                        active: false
                        deptId: 9
                        jobTitle: null
                        type: null
                        officeId: 3
                        staffManagerId: null
                    deid_staff_aggregate:
                      aggregate:
                        count: 138
                real_api_response:
                  summary: Sample from actual API response
                  value:
                    deid_staff:
                      - id: 244
                        pmsRef: '2426'
                        firstName: Lacy
                        lastName: Armstrong
                        email: danial.hills@yahoo.com
                        active: true
                        deptId: 7
                        jobTitle: Analyst
                        type: Part-time
                        officeId: 2
                        staffManagerId: 202
                      - id: 267
                        pmsRef: '2485'
                        firstName: Marion
                        lastName: Auer
                        email: sammy.heathcote@gmail.com
                        active: true
                        deptId: 7
                        jobTitle: null
                        type: null
                        officeId: 1
                        staffManagerId: null
                    deid_staff_aggregate:
                      aggregate:
                        count: 138
                empty_response:
                  summary: No staff found
                  value:
                    deid_staff: []
                    deid_staff_aggregate:
                      aggregate:
                        count: 0
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              examples:
                invalid_department_id:
                  summary: Invalid department ID
                  value:
                    error: departmentId must be a positive integer
                    code: INVALID_DEPARTMENT_ID
                invalid_page:
                  summary: Invalid page number
                  value:
                    error: page must be non-negative
                    code: INVALID_PAGE
        '401':
          description: Unauthorized - insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              examples:
                insufficient_permissions:
                  summary: User lacks required role
                  value:
                    error: Access denied. Missing Roles
                    code: INSUFFICIENT_PERMISSIONS
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
  /gql/v1/staff/search:
    post:
      tags:
        - Staff
      summary: Search staff
      description: >
        **Advanced staff filtering with custom GraphQL where clauses and dynamic
        ordering**


        Provides flexible, enterprise-grade filtering for staff directory
        queries with boolean logic,

        relationship traversal, and multi-field ordering.


        Key capabilities include boolean operators (`_and`, `_or`, `_not`), text
        matching (`_ilike`),

        comparison operators (`_gt`, `_gte`, `_lt`, `_lte`, `_eq`, `_neq`),
        array operators (`_in`, `_nin`),

        and nested/related filtering (e.g., by office or manager).


        Real Example:

        ```bash

        curl --location 'https://{{host}}/v1/staff/search' \

        --header 'Authorization: bearer {{token}}' \

        --header 'Content-Type: application/json' \

        --data '{
          "pageSize": 1,
          "where": {
            "_and": [
              {
                "_or": [
                  {
                    "firstName": {
                      "_ilike": "%john%"
                    }
                  },
                  {
                    "lastName": {
                      "_ilike": "%doe%"
                    }
                  }
                ]
              },
              {
                "active": {
                  "_eq": true
                }
              },
              {
                "createdAt": {
                  "_gte": "1900-01-01T00:00:00Z"
                }
              },
              {
                "deptId": {
                  "_in": [
                    1,
                    2,
                    3
                  ]
                }
              }
            ]
          },
          "orderBy": [
            {
              "lastName": "asc"
            },
            {
              "firstName": "asc"
            }
          ]
        }'

        ```
      operationId: filterStaffDynamic
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                limit:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 1
                  description: Maximum number of staff to return
                  example: 1
                where:
                  type: object
                  description: GraphQL-style where clause for complex staff filtering
                  example:
                    _and:
                      - _or:
                          - firstName:
                              _ilike: '%john%'
                          - lastName:
                              _ilike: '%doe%'
                      - active:
                          _eq: true
                      - createdAt:
                          _gte: '1900-01-01T00:00:00Z'
                      - deptId:
                          _in:
                            - 1
                            - 2
                            - 3
                orderBy:
                  type: array
                  description: Dynamic ordering specifications with multiple fields
                  items:
                    type: object
                  example:
                    - lastName: asc
                    - firstName: asc
      responses:
        '200':
          description: Successfully retrieved filtered staff with dynamic ordering
          content:
            application/json:
              schema:
                type: object
                properties:
                  staff:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Unique staff identifier
                          example: 202
                        pmsRef:
                          type: string
                          description: PMS reference identifier
                          example: '2254'
                        firstName:
                          type: string
                          description: Staff member first name
                          example: Holley
                        lastName:
                          type: string
                          description: Staff member last name
                          example: Abbott
                        email:
                          type: string
                          format: email
                          description: Primary email address
                          example: ena.toy@hotmail.com
                        active:
                          type: boolean
                          description: Whether the staff member is active
                          example: true
                        deptId:
                          type: integer
                          description: Department identifier
                          example: 8
                        jobTitle:
                          type: string
                          nullable: true
                          description: Job title of the staff member
                          example: null
                        type:
                          type: string
                          nullable: true
                          description: Staff member type or category
                          example: null
                        officeId:
                          type: integer
                          description: Office identifier where the staff member is based
                          example: 2
                        staffManagerId:
                          type: integer
                          nullable: true
                          description: Identifier of the staff member's manager
                          example: null
                  total:
                    type: object
                    properties:
                      aggregate:
                        type: object
                        properties:
                          count:
                            type: integer
                            description: Total number of staff records matching criteria
                            example: 1
              examples:
                filtered_response:
                  summary: Filtered staff with dynamic ordering
                  value:
                    staff:
                      - id: 202
                        pmsRef: '2254'
                        firstName: Holley
                        lastName: Abbott
                        email: ena.toy@hotmail.com
                        active: true
                        deptId: 8
                        jobTitle: null
                        type: null
                        officeId: 2
                        staffManagerId: null
                    total:
                      aggregate:
                        count: 1
                empty_response:
                  summary: No staff found matching criteria
                  value:
                    staff: []
                    total:
                      aggregate:
                        count: 0
        '400':
          description: Bad request - invalid where/orderBy
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /gql/v1/staff/{id}:
    get:
      tags:
        - Staff
      summary: Get staff member by ID
      description: |
        **Retrieve a specific staff member by their unique identifier**

        This endpoint provides basic staff member information including:
        - Staff member identification and PMS reference
        - Personal details (name and email)
        - Employment status and organizational structure
        - Department and office assignments
        - Management hierarchy information

        **Staff Details Include:**
        - Staff member ID and PMS reference
        - Personal information (first name, last name, email)
        - Active status indicator
        - Department and office identifiers
        - Job title and staff type (when available)
        - Manager assignment (when applicable)

        **Business Applications:**
        - Staff member lookup and verification
        - Organizational structure queries
        - Basic staff information retrieval
        - Department and office staff management

        **Real Example:**
        ```bash
        curl --location 'https://{{host}}/v1/staff/123' \
        --header 'Authorization: bearer {{token}}' \
        --header 'Content-Type: application/json'
        ```

        **Response Example:**
        ```json
        {
          "id": 202,
          "pmsRef": "2254",
          "firstName": "Holley",
          "lastName": "Abbott",
          "email": "ena.toy@hotmail.com",
          "active": true,
          "deptId": 8,
          "jobTitle": null,
          "type": null,
          "officeId": 2,
          "staffManagerId": null
        }
        ```
      operationId: getStaffById
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier of the staff member
          schema:
            type: integer
            minimum: 1
          example: 123
      responses:
        '200':
          description: Staff member details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: Unique staff member identifier
                    example: 202
                  pmsRef:
                    type: string
                    description: PMS reference identifier
                    example: '2254'
                  firstName:
                    type: string
                    description: Staff member first name
                    example: Holley
                  lastName:
                    type: string
                    description: Staff member last name
                    example: Abbott
                  email:
                    type: string
                    format: email
                    description: Primary email address
                    example: ena.toy@hotmail.com
                  active:
                    type: boolean
                    description: Whether the staff member is active
                    example: true
                  deptId:
                    type: integer
                    description: Department identifier
                    example: 8
                  jobTitle:
                    type: string
                    nullable: true
                    description: Job title of the staff member
                    example: null
                  type:
                    type: string
                    nullable: true
                    description: Staff member type or category
                    example: null
                  officeId:
                    type: integer
                    description: Office identifier where the staff member is based
                    example: 2
                  staffManagerId:
                    type: integer
                    nullable: true
                    description: Identifier of the staff member's manager
                    example: null
        '401':
          description: Unauthorized - Invalid or missing authentication token
        '403':
          description: Forbidden - Insufficient permissions to access this staff member
        '404':
          description: Staff member not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Staff member not found
                  message:
                    type: string
                    example: Staff member with ID 123 does not exist
        '500':
          description: Internal server error
  /gql/v1/invoices:
    post:
      tags:
        - Invoices
      summary: List invoices
      description: |
        **Retrieve invoices with comprehensive filtering and financial data**

        This endpoint delivers complete invoice management functionality with:
        - Advanced pagination for large invoice datasets
        - Multi-dimensional filtering (client, status, date ranges)
        - Integration with AR transactions for complete financial context
        - Tax, interest, and payment status tracking
        - Client relationship data for each invoice
        - Aggregate counting for reporting and analytics

        **Key Financial Features:**
        - Invoice status tracking (PENDING, PAID, OVERDUE, POSTED, etc.)
        - Tax and interest calculations included
        - Due date monitoring for collections management
        - AR transaction linkage for payment reconciliation
        - Amount and allocation tracking for financial reporting

        **Filtering Capabilities:**
        - Client-specific invoice retrieval
        - Status-based filtering for workflow management  
        - Date range queries for period reporting
        - Sorting by creation date or transaction date

        **Business Applications:**
        - Accounts receivable management and aging reports
        - Client billing history and statement generation
        - Collections management and overdue tracking
        - Financial reporting and revenue recognition
        - Payment reconciliation and allocation tracking

        **Real Example:**
        ```bash
        curl --location 'https://{{host}}/v1/invoices' \
        --header 'Authorization: bearer {{token}} \
        --header 'Content-Type: application/json' \
        --data '{
          "pageSize": 25,
          "page": 0
        }'
        ```
      operationId: getInvoices
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                pageSize:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 25
                  description: Maximum number of invoice records to return
                  example: 25
                page:
                  type: integer
                  minimum: 0
                  default: 0
                  description: Page number for pagination (0-based)
                  example: 0
                clientId:
                  type: integer
                  description: Filter invoices by specific client ID
                  example: 7720
                status:
                  type: string
                  description: Filter by invoice status
                  enum:
                    - PENDING
                    - POSTED
                    - PAID
                    - OVERDUE
                    - CANCELLED
                    - DRAFT
                  example: POSTED
                startDate:
                  type: string
                  format: date-time
                  description: Start date for invoice date range filter
                  example: '1990-01-01T00:00:00'
                endDate:
                  type: string
                  format: date-time
                  description: End date for invoice date range filter
                  example: '2024-12-31T23:59:59'
                sortOrder:
                  type: string
                  enum:
                    - asc
                    - desc
                  default: desc
                  description: Sort order for invoice dates
                  example: desc
            examples:
              default_pagination:
                summary: Default pagination
                value:
                  pageSize: 25
                  page: 0
      responses:
        '200':
          description: Successfully retrieved invoice records
          content:
            application/json:
              schema:
                type: object
                properties:
                  deid_invoice:
                    type: array
                    items:
                      type: object
                      properties:
                        arTranId:
                          type: integer
                          description: Associated AR transaction identifier
                          example: 125890
                        invoiceNumber:
                          type: string
                          description: Unique invoice number for client reference
                          example: INV-2024-4850
                        dueDate:
                          type: string
                          format: date-time
                          description: Invoice payment due date
                          example: '2024-04-24T05:00:00'
                        status:
                          type: string
                          description: Current invoice status
                          example: POSTED
                        tax:
                          type: number
                          format: decimal
                          description: Tax amount charged on invoice
                          example: 0
                        interest:
                          type: number
                          format: decimal
                          description: Interest charges applied to invoice
                          example: 0
                        description:
                          type: string
                          nullable: true
                          description: Additional invoice description or notes
                          example: null
                        createdAt:
                          type: string
                          format: date-time
                          description: Invoice record creation timestamp
                          example: '2024-05-12T22:50:20.595961+00:00'
                        updatedAt:
                          type: string
                          format: date-time
                          description: Invoice record last update timestamp
                          example: '2024-05-12T22:50:20.595961+00:00'
                        ar_tran:
                          type: object
                          description: Associated AR transaction details
                          properties:
                            id:
                              type: integer
                              example: 125890
                            pmsRef:
                              type: string
                              description: Practice management system reference
                              example: '240815'
                            transactionDate:
                              type: string
                              format: date-time
                              description: Transaction date
                              example: '2024-03-22T05:00:00'
                            amount:
                              type: number
                              format: decimal
                              description: Transaction amount
                              example: 4250
                            allocated:
                              type: number
                              format: decimal
                              description: Allocated amount
                              example: 4250
                            clientId:
                              type: integer
                              description: Client identifier
                              example: 7720
                            client:
                              type: object
                              properties:
                                id:
                                  type: integer
                                  example: 7720
                                name:
                                  type: string
                                  example: TechFlow Enterprises
                  deid_invoice_aggregate:
                    type: object
                    properties:
                      aggregate:
                        type: object
                        properties:
                          count:
                            type: integer
                            description: Total number of invoice records matching criteria
                            example: 94
              examples:
                successful_response:
                  summary: Invoice records with AR transaction details
                  value:
                    deid_invoice:
                      - arTranId: 125890
                        invoiceNumber: INV-2024-4850
                        dueDate: '2024-04-24T05:00:00'
                        status: POSTED
                        tax: 0
                        interest: 0
                        description: null
                        createdAt: '2024-05-12T22:50:20.595961+00:00'
                        updatedAt: '2024-05-12T22:50:20.595961+00:00'
                        ar_tran:
                          id: 125890
                          pmsRef: '240815'
                          transactionDate: '2024-03-22T05:00:00'
                          amount: 4250
                          allocated: 4250
                          clientId: 7720
                          client:
                            id: 7720
                            name: TechFlow Enterprises
                      - arTranId: 125234
                        invoiceNumber: INV-2024-4721
                        dueDate: '2024-03-03T05:00:00'
                        status: POSTED
                        tax: 0
                        interest: 0
                        description: null
                        createdAt: '2024-05-12T22:50:10.982058+00:00'
                        updatedAt: '2024-05-12T22:50:10.982058+00:00'
                        ar_tran:
                          id: 125234
                          pmsRef: '239842'
                          transactionDate: '2024-02-04T05:00:00'
                          amount: 3750
                          allocated: 3750
                          clientId: 7720
                          client:
                            id: 7720
                            name: TechFlow Enterprises
                      - arTranId: 124856
                        invoiceNumber: INV-2024-4592
                        dueDate: '2024-02-07T05:00:00'
                        status: POSTED
                        tax: 0
                        interest: 0
                        description: null
                        createdAt: '2024-05-12T22:50:09.194501+00:00'
                        updatedAt: '2024-05-12T22:50:09.194501+00:00'
                        ar_tran:
                          id: 124856
                          pmsRef: '238967'
                          transactionDate: '2024-01-08T05:00:00'
                          amount: 2850
                          allocated: 2850
                          clientId: 7720
                          client:
                            id: 7720
                            name: TechFlow Enterprises
                    deid_invoice_aggregate:
                      aggregate:
                        count: 94
                real_api_response:
                  summary: Sample from actual API response
                  value:
                    deid_invoice:
                      - arTranId: 119859
                        invoiceNumber: '4618'
                        dueDate: '2023-03-24T05:00:00'
                        status: POSTED
                        tax: 0
                        interest: 0
                        description: null
                        createdAt: '2023-05-12T22:50:20.595961+00:00'
                        updatedAt: '2023-05-12T22:50:20.595961+00:00'
                        ar_tran:
                          id: 119859
                          pmsRef: '224081'
                          transactionDate: '2023-02-22T05:00:00'
                          amount: 0
                          allocated: 0
                          clientId: 7720
                          client:
                            id: 7720
                            name: Kendrick Harris
                      - arTranId: 96162
                        invoiceNumber: '74080'
                        dueDate: '2018-10-11T04:00:00'
                        status: POSTED
                        tax: 0
                        interest: 0
                        description: null
                        createdAt: '2023-05-12T22:50:08.928921+00:00'
                        updatedAt: '2023-05-12T22:50:08.928921+00:00'
                        ar_tran:
                          id: 96162
                          pmsRef: '108840'
                          transactionDate: '2018-09-11T04:00:00'
                          amount: 3516
                          allocated: 3516
                          clientId: 7720
                          client:
                            id: 7720
                            name: Kendrick Harris
                    deid_invoice_aggregate:
                      aggregate:
                        count: 94
                empty_response:
                  summary: No invoices found
                  value:
                    deid_invoice: []
                    deid_invoice_aggregate:
                      aggregate:
                        count: 0
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              examples:
                invalid_date_range:
                  summary: Invalid date range
                  value:
                    error: startDate must be before or equal to endDate
                    code: INVALID_DATE_RANGE
                invalid_client_id:
                  summary: Invalid client ID
                  value:
                    error: clientId must be a positive integer
                    code: INVALID_CLIENT_ID
        '401':
          description: Unauthorized - missing or invalid admin secret
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              examples:
                missing_auth:
                  summary: Missing authentication header
                  value:
                    error: x-hasura-admin-secret header is required
                    code: MISSING_AUTH_HEADER
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
  /gql/v1/invoices/search:
    post:
      tags:
        - Invoices
      summary: Search invoices
      description: >
        **Advanced invoice filtering with custom GraphQL where clauses and
        dynamic ordering**


        Supports invoiceNumber text matching, status filtering, and date ranges.


        Real Example:

        ```bash

        curl --location 'https://{{host}}/v1/invoices/search' \

        --header 'Authorization: bearer {{token}}' \

        --header 'Content-Type: application/json' \

        --data '{
          "pageSize": 1,
          "where": {
            "_and": [
              {
                "_or": [
                  {
                    "invoiceNumber": {
                      "_ilike": "%2024%"
                    }
                  },
                  {
                    "description": {
                      "_ilike": "%service%"
                    }
                  }
                ]
              },
              {
                "status": {
                  "_in": ["POSTED", "CLOSED"]
                }
              },
              {
                "createdAt": {
                  "_gte": "1900-01-01T00:00:00Z"
                }
              },
              {
                "dueDate": {
                  "_gte": "2024-01-01T00:00:00Z"
                }
              }
            ]
          },
          "orderBy": [
            {
              "invoiceNumber": "asc"
            },
            {
              "createdAt": "desc"
            }
          ]
        }'

        ```
      operationId: filterInvoicesDynamic
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                pageSize:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 1
                where:
                  type: object
                  description: GraphQL-style where clause for complex invoice filtering
                  example:
                    _and:
                      - _or:
                          - invoiceNumber:
                              _ilike: '%2024%'
                          - description:
                              _ilike: '%service%'
                      - status:
                          _in:
                            - POSTED
                            - CLOSED
                      - createdAt:
                          _gte: '1900-01-01T00:00:00Z'
                      - dueDate:
                          _gte: '2024-01-01T00:00:00Z'
                orderBy:
                  type: array
                  items:
                    type: object
                  description: Dynamic ordering specifications
                  example:
                    - invoiceNumber: asc
                    - createdAt: desc
      responses:
        '200':
          description: Successfully retrieved filtered invoices
        '400':
          description: Bad request - invalid where/orderBy
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /gql/v1/invoice/{id}:
    get:
      tags:
        - Invoices
      summary: Get invoice by ID
      description: |
        **Retrieve a specific invoice by its unique identifier**

        This endpoint provides detailed invoice information including:
        - Complete invoice details and line items
        - Invoice status and payment tracking
        - Client and project relationships
        - Tax calculations and compliance data
        - Payment history and outstanding balances
        - Document generation and delivery status

        **Invoice Management Features:**
        - Invoice lifecycle tracking
        - Payment status monitoring
        - Tax calculation and compliance
        - Client relationship integration
        - Document generation and delivery

        **Invoice Details Include:**
        - Invoice number and reference
        - Invoice status and payment status
        - Client and project information
        - Line items and amounts
        - Tax calculations
        - Payment history

        **Business Applications:**
        - Invoice status monitoring
        - Payment tracking and reconciliation
        - Client billing history
        - Revenue recognition analysis
        - Tax compliance reporting

        **Real Example:**
        ```bash
        curl --location 'https://{{host}}/v1/invoice/45678' \
        --header 'Authorization: bearer {{token}}' \
        --header 'Content-Type: application/json'
        ```

        **Response Example:**
        ```json
        {
          "id": 45678,
          "invoiceNumber": "INV-2024-001",
          "reference": "Q4-AUDIT-2024",
          "status": "SENT",
          "paymentStatus": "PARTIALLY_PAID",
          "clientId": 789,
          "clientName": "Acme Corporation",
          "clientEmail": "billing@acme.com",
          "projectId": 67890,
          "projectName": "Q4 Financial Audit",
          "issueDate": "2024-12-01T00:00:00Z",
          "dueDate": "2024-12-31T23:59:59Z",
          "subtotal": 20000.00,
          "taxAmount": 2000.00,
          "totalAmount": 22000.00,
          "currency": "USD",
          "paidAmount": 15000.00,
          "outstandingAmount": 7000.00,
          "lineItems": [
            {
              "id": 1,
              "description": "Financial Statement Audit",
              "quantity": 80,
              "unitPrice": 250.00,
              "amount": 20000.00,
              "taxRate": 0.10
            }
          ],
          "payments": [
            {
              "id": 12345,
              "amount": 15000.00,
              "paymentDate": "2024-12-15T10:30:00Z",
              "paymentMethod": "CREDIT_CARD",
              "status": "CONFIRMED"
            }
          ],
          "notes": "Payment due within 30 days of invoice date",
          "createdAt": "2024-12-01T09:00:00Z",
          "updatedAt": "2024-12-15T10:30:00Z"
        }
        ```
      operationId: getInvoiceById
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier of the invoice
          schema:
            type: integer
            minimum: 1
          example: 45678
      responses:
        '200':
          description: Invoice details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: Unique invoice identifier
                    example: 45678
                  invoiceNumber:
                    type: string
                    description: Invoice number
                    example: INV-2024-001
                  reference:
                    type: string
                    description: Invoice reference or description
                    example: Q4-AUDIT-2024
                  status:
                    type: string
                    description: Invoice status
                    enum:
                      - DRAFT
                      - SENT
                      - VIEWED
                      - PAID
                      - OVERDUE
                      - CANCELLED
                    example: SENT
                  paymentStatus:
                    type: string
                    description: Payment status
                    enum:
                      - UNPAID
                      - PARTIALLY_PAID
                      - PAID
                      - OVERDUE
                    example: PARTIALLY_PAID
                  clientId:
                    type: integer
                    description: Associated client identifier
                    example: 789
                  clientName:
                    type: string
                    description: Client name
                    example: Acme Corporation
                  clientEmail:
                    type: string
                    description: Client billing email
                    example: billing@acme.com
                  projectId:
                    type: integer
                    description: Associated project identifier
                    example: 67890
                  projectName:
                    type: string
                    description: Project name
                    example: Q4 Financial Audit
                  issueDate:
                    type: string
                    format: date-time
                    description: Invoice issue date
                    example: '2024-12-01T00:00:00Z'
                  dueDate:
                    type: string
                    format: date-time
                    description: Invoice due date
                    example: '2024-12-31T23:59:59Z'
                  subtotal:
                    type: number
                    format: decimal
                    description: Invoice subtotal before tax
                    example: 20000
                  taxAmount:
                    type: number
                    format: decimal
                    description: Total tax amount
                    example: 2000
                  totalAmount:
                    type: number
                    format: decimal
                    description: Total invoice amount including tax
                    example: 22000
                  currency:
                    type: string
                    description: Invoice currency code
                    example: USD
                  paidAmount:
                    type: number
                    format: decimal
                    description: Total amount paid to date
                    example: 15000
                  outstandingAmount:
                    type: number
                    format: decimal
                    description: Outstanding balance
                    example: 7000
                  lineItems:
                    type: array
                    description: Invoice line items
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Line item identifier
                          example: 1
                        description:
                          type: string
                          description: Line item description
                          example: Financial Statement Audit
                        quantity:
                          type: number
                          format: decimal
                          description: Quantity of units
                          example: 80
                        unitPrice:
                          type: number
                          format: decimal
                          description: Unit price
                          example: 250
                        amount:
                          type: number
                          format: decimal
                          description: Line item total amount
                          example: 20000
                        taxRate:
                          type: number
                          format: decimal
                          description: Tax rate applied
                          example: 0.1
                  payments:
                    type: array
                    description: Payment history for this invoice
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Payment identifier
                          example: 12345
                        amount:
                          type: number
                          format: decimal
                          description: Payment amount
                          example: 15000
                        paymentDate:
                          type: string
                          format: date-time
                          description: Payment date
                          example: '2024-12-15T10:30:00Z'
                        paymentMethod:
                          type: string
                          description: Payment method used
                          enum:
                            - CREDIT_CARD
                            - DEBIT_CARD
                            - ACH
                            - BANK_TRANSFER
                            - CHECK
                            - WIRE
                            - PAYPAL
                          example: CREDIT_CARD
                        status:
                          type: string
                          description: Payment status
                          enum:
                            - PENDING
                            - CONFIRMED
                            - FAILED
                            - CANCELLED
                          example: CONFIRMED
                  notes:
                    type: string
                    description: Additional notes or terms
                    example: Payment due within 30 days of invoice date
                  createdAt:
                    type: string
                    format: date-time
                    description: Invoice creation timestamp
                    example: '2024-12-01T09:00:00Z'
                  updatedAt:
                    type: string
                    format: date-time
                    description: Last update timestamp
                    example: '2024-12-15T10:30:00Z'
        '401':
          description: Unauthorized - Invalid or missing authentication token
        '403':
          description: Forbidden - Insufficient permissions to access this invoice
        '404':
          description: Invoice not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invoice not found
                  message:
                    type: string
                    example: Invoice with ID 45678 does not exist
        '500':
          description: Internal server error
  /gql/v1/payments:
    post:
      tags:
        - Payments
      summary: List payments
      description: >
        **Retrieve payment records with transaction details and security
        compliance**


        This endpoint provides secure payment data access with:

        - PCI-compliant payment information (masked card data)

        - Payment method categorization and tracking

        - Integration with AR transactions for complete context

        - Payment processor integration (PayPal, Stripe, etc.)

        - Date-based filtering for reconciliation periods

        - Client relationship data for payment attribution


        **Security & Compliance:**

        - PCI DSS compliant data handling (last 4 digits only)

        - Secure payment processor ID tracking

        - Payment confirmation date logging

        - Audit trail for payment processing


        **Payment Method Support:**

        - Credit/debit card payments with masked PAN

        - ACH/bank transfer processing

        - Check and wire transfer tracking

        - Digital wallet integration (PayPal, Apple Pay, etc.)


        **Reconciliation Features:**

        - Payment-to-invoice matching via AR transactions

        - Payment confirmation status tracking

        - Processor reference ID management

        - Multi-currency payment support


        **Business Applications:**

        - Payment reconciliation and matching

        - Revenue recognition and cash flow analysis

        - Client payment history and patterns

        - Payment method performance analysis

        - Compliance reporting and audit trails


        **Real Example:**

        ```bash

        curl --location 'https://{{host}}/v1/payments' \

        --header 'Authorization: bearer {{token}} \

        --header 'Content-Type: application/json' \

        --data '{
          "pageSize": 25,
          "page": 0
        }'

        ```
      operationId: getPayments
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                pageSize:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 25
                  description: Maximum number of payment records to return
                  example: 25
                page:
                  type: integer
                  minimum: 0
                  default: 0
                  description: Page number for pagination (0-based)
                  example: 0
                clientId:
                  type: integer
                  description: Filter payments by specific client ID
                  example: 789
                paymentMethod:
                  type: string
                  description: Filter by payment method type
                  enum:
                    - CREDIT_CARD
                    - DEBIT_CARD
                    - ACH
                    - BANK_TRANSFER
                    - CHECK
                    - WIRE
                    - PAYPAL
                    - APPLE_PAY
                    - GOOGLE_PAY
                  example: CREDIT_CARD
                startDate:
                  type: string
                  format: date-time
                  description: Start date for payment date range filter
                  example: '2024-01-01T00:00:00'
                endDate:
                  type: string
                  format: date-time
                  description: End date for payment date range filter
                  example: '2024-12-31T23:59:59'
                status:
                  type: string
                  description: Filter by payment status
                  enum:
                    - PENDING
                    - CONFIRMED
                    - FAILED
                    - CANCELLED
                    - REFUNDED
                  example: CONFIRMED
                sortOrder:
                  type: string
                  enum:
                    - asc
                    - desc
                  default: desc
                  description: Sort order for payment date
                  example: desc
            examples:
              default_pagination:
                summary: Default pagination
                value:
                  pageSize: 25
                  page: 0
      responses:
        '200':
          description: Successfully retrieved payment records
          content:
            application/json:
              schema:
                type: object
                properties:
                  deid_payment:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Unique payment identifier
                          example: 45201
                        arTranId:
                          type: integer
                          description: Associated AR transaction identifier
                          example: 125890
                        paymentMethod:
                          type: string
                          description: Payment method type
                          example: CREDIT_CARD
                        amount:
                          type: number
                          format: decimal
                          description: Payment amount
                          example: 2750
                        paymentDate:
                          type: string
                          format: date-time
                          description: Date when payment was processed
                          example: '2024-03-15T14:30:22+00:00'
                        confirmationDate:
                          type: string
                          format: date-time
                          nullable: true
                          description: Date when payment was confirmed
                          example: '2024-03-15T14:32:18+00:00'
                        status:
                          type: string
                          description: Current payment status
                          example: CONFIRMED
                        processorId:
                          type: string
                          description: Payment processor identifier
                          example: stripe
                        processorReferenceId:
                          type: string
                          description: Payment processor transaction reference
                          example: pi_3N1K2mL4uZ5v6w7x8y9z0a1b
                        last4Digits:
                          type: string
                          nullable: true
                          description: Last 4 digits of card (PCI compliant)
                          example: '4242'
                        cardType:
                          type: string
                          nullable: true
                          description: Credit card type
                          example: VISA
                        currency:
                          type: string
                          description: Payment currency code
                          example: USD
                        clientId:
                          type: integer
                          description: Associated client identifier
                          example: 789
                        createdAt:
                          type: string
                          format: date-time
                          description: Payment record creation timestamp
                          example: '2024-03-15T14:30:22.123456+00:00'
                        updatedAt:
                          type: string
                          format: date-time
                          description: Payment record last update timestamp
                          example: '2024-03-15T14:32:18.789012+00:00'
                        client:
                          type: object
                          description: Associated client information
                          properties:
                            id:
                              type: integer
                              example: 789
                            name:
                              type: string
                              example: TechFlow Enterprises
                            clientRef:
                              type: string
                              example: TF-2024-789
                        ar_tran:
                          type: object
                          description: Associated AR transaction details
                          properties:
                            id:
                              type: integer
                              example: 125890
                            pmsRef:
                              type: string
                              example: INV-2024-3456
                            transactionDate:
                              type: string
                              format: date-time
                              example: '2024-03-01T00:00:00+00:00'
                            amount:
                              type: number
                              format: decimal
                              example: 2750
                  deid_payment_aggregate:
                    type: object
                    properties:
                      aggregate:
                        type: object
                        properties:
                          count:
                            type: integer
                            description: Total number of payment records matching criteria
                            example: 15
                          sum:
                            type: object
                            properties:
                              amount:
                                type: number
                                format: decimal
                                description: >-
                                  Total payment amount across all matching
                                  records
                                example: 28750
              examples:
                successful_response:
                  summary: >-
                    Payment records with security compliance and transaction
                    details
                  value:
                    deid_payment:
                      - id: 45201
                        arTranId: 125890
                        paymentMethod: CREDIT_CARD
                        amount: 2750
                        paymentDate: '2024-03-15T14:30:22+00:00'
                        confirmationDate: '2024-03-15T14:32:18+00:00'
                        status: CONFIRMED
                        processorId: stripe
                        processorReferenceId: pi_3N1K2mL4uZ5v6w7x8y9z0a1b
                        last4Digits: '4242'
                        cardType: VISA
                        currency: USD
                        clientId: 789
                        createdAt: '2024-03-15T14:30:22.123456+00:00'
                        updatedAt: '2024-03-15T14:32:18.789012+00:00'
                        client:
                          id: 789
                          name: TechFlow Enterprises
                          clientRef: TF-2024-789
                        ar_tran:
                          id: 125890
                          pmsRef: INV-2024-3456
                          transactionDate: '2024-03-01T00:00:00+00:00'
                          amount: 2750
                      - id: 45202
                        arTranId: 125891
                        paymentMethod: ACH
                        amount: 1850
                        paymentDate: '2024-03-12T09:15:33+00:00'
                        confirmationDate: '2024-03-14T10:22:45+00:00'
                        status: CONFIRMED
                        processorId: plaid
                        processorReferenceId: ach_3M9H8gJ2tX4v5w6z7y8a9b0c
                        last4Digits: '5678'
                        cardType: null
                        currency: USD
                        clientId: 789
                        createdAt: '2024-03-12T09:15:33.456789+00:00'
                        updatedAt: '2024-03-14T10:22:45.123456+00:00'
                        client:
                          id: 789
                          name: TechFlow Enterprises
                          clientRef: TF-2024-789
                        ar_tran:
                          id: 125891
                          pmsRef: INV-2024-3457
                          transactionDate: '2024-02-28T00:00:00+00:00'
                          amount: 1850
                      - id: 45203
                        arTranId: 125892
                        paymentMethod: PAYPAL
                        amount: 3250
                        paymentDate: '2024-03-10T16:45:12+00:00'
                        confirmationDate: '2024-03-10T16:47:08+00:00'
                        status: CONFIRMED
                        processorId: paypal
                        processorReferenceId: PAYID-M2K4L6Y8Z9A1B2C3D4E5F6G7
                        last4Digits: null
                        cardType: null
                        currency: USD
                        clientId: 789
                        createdAt: '2024-03-10T16:45:12.789012+00:00'
                        updatedAt: '2024-03-10T16:47:08.345678+00:00'
                        client:
                          id: 789
                          name: TechFlow Enterprises
                          clientRef: TF-2024-789
                        ar_tran:
                          id: 125892
                          pmsRef: INV-2024-3458
                          transactionDate: '2024-02-25T00:00:00+00:00'
                          amount: 3250
                    deid_payment_aggregate:
                      aggregate:
                        count: 15
                        sum:
                          amount: 28750
                empty_response:
                  summary: No payments found
                  value:
                    deid_payment: []
                    deid_payment_aggregate:
                      aggregate:
                        count: 0
                        sum:
                          amount: 0
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              examples:
                invalid_date_range:
                  summary: Invalid date range
                  value:
                    error: startDate must be before or equal to endDate
                    code: INVALID_DATE_RANGE
                invalid_payment_method:
                  summary: Invalid payment method
                  value:
                    error: Invalid payment method specified
                    code: INVALID_PAYMENT_METHOD
        '401':
          description: Unauthorized - missing or invalid admin secret
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              examples:
                missing_auth:
                  summary: Missing authentication header
                  value:
                    error: x-hasura-admin-secret header is required
                    code: MISSING_AUTH_HEADER
        '403':
          description: Forbidden - insufficient permissions for payment data access
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              examples:
                insufficient_permissions:
                  summary: Insufficient permissions for payment data
                  value:
                    error: Access to payment data requires elevated permissions
                    code: INSUFFICIENT_PAYMENT_PERMISSIONS
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
  /gql/v1/payments/search:
    post:
      tags:
        - Payments
      summary: Search payments
      description: >
        **Advanced payment filtering with custom GraphQL where clauses and
        dynamic ordering**


        Backed by view `vw_payment_history_firm_table`. Supports text matching,
        date ranges, and flags.


        Real Example:

        ```bash

        curl --location 'https://{{host}}/v1/payments/search' \

        --header 'Authorization: bearer {{token}}' \

        --header 'Content-Type: application/json' \

        --data '{
          "pageSize": 1,
          "where": {
            "_and": [
              {
                "_or": [
                  {
                    "paymentMethod": {
                      "_ilike": "%CREDIT%"
                    }
                  },
                  {
                    "cardType": {
                      "_ilike": "%VISA%"
                    }
                  }
                ]
              },
              {
                "isAutomatic": {
                  "_eq": false
                }
              },
              {
                "createdAt": {
                  "_gte": "1900-01-01T00:00:00Z"
                }
              },
              {
                "paymentConfirmationDate": {
                  "_is_null": false
                }
              }
            ]
          },
          "orderBy": [
            {
              "paymentConfirmationDate": "desc"
            },
            {
              "createdAt": "desc"
            }
          ]
        }'

        ```
      operationId: filterPaymentsDynamic
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                pageSize:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 1
                where:
                  type: object
                  description: GraphQL-style where clause for complex payment filtering
                  example:
                    _and:
                      - _or:
                          - paymentMethod:
                              _ilike: '%CREDIT%'
                          - cardType:
                              _ilike: '%VISA%'
                      - isAutomatic:
                          _eq: false
                      - createdAt:
                          _gte: '1900-01-01T00:00:00Z'
                      - paymentConfirmationDate:
                          _is_null: false
                orderBy:
                  type: array
                  items:
                    type: object
                  description: Dynamic ordering specifications
                  example:
                    - paymentConfirmationDate: desc
                    - createdAt: desc
      responses:
        '200':
          description: Successfully retrieved filtered payments
        '400':
          description: Bad request - invalid where/orderBy
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /gql/v1/payment/{id}:
    get:
      tags:
        - Payments
      summary: Get payment by ID
      description: |
        **Retrieve a specific payment by its unique identifier**

        This endpoint provides detailed payment information including:
        - Complete payment transaction details
        - PCI-compliant payment method information (masked)
        - Payment status and confirmation data
        - Associated invoice and client relationships
        - Payment processor integration details
        - Audit trail and security compliance data

        **Security & Compliance:**
        - PCI DSS compliant data handling
        - Secure payment processor ID tracking
        - Payment confirmation date logging
        - Audit trail for payment processing

        **Payment Details Include:**
        - Payment amount and currency
        - Payment method (masked for security)
        - Payment status and confirmation
        - Associated invoice references
        - Client relationship data
        - Payment processor details

        **Business Applications:**
        - Payment verification and reconciliation
        - Client payment history lookup
        - Payment dispute resolution
        - Audit and compliance reporting
        - Payment method analysis

        **Real Example:**
        ```bash
        curl --location 'https://{{host}}/v1/payment/12345' \
        --header 'Authorization: bearer {{token}}' \
        --header 'Content-Type: application/json'
        ```

        **Response Example:**
        ```json
        {
          "id": 12345,
          "amount": 1500.00,
          "currency": "USD",
          "paymentMethod": "CREDIT_CARD",
          "cardLastFour": "1234",
          "cardType": "VISA",
          "status": "CONFIRMED",
          "confirmationDate": "2024-01-15T10:30:00Z",
          "processorReference": "stripe_pi_1234567890",
          "clientId": 789,
          "clientName": "Acme Corporation",
          "invoiceId": 456,
          "invoiceNumber": "INV-2024-001",
          "createdAt": "2024-01-15T10:25:00Z",
          "updatedAt": "2024-01-15T10:30:00Z"
        }
        ```
      operationId: getPaymentById
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier of the payment
          schema:
            type: integer
            minimum: 1
          example: 12345
      responses:
        '200':
          description: Payment details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: Unique payment identifier
                    example: 12345
                  amount:
                    type: number
                    format: decimal
                    description: Payment amount
                    example: 1500
                  currency:
                    type: string
                    description: Payment currency code
                    example: USD
                  paymentMethod:
                    type: string
                    description: Method used for payment
                    enum:
                      - CREDIT_CARD
                      - DEBIT_CARD
                      - ACH
                      - BANK_TRANSFER
                      - CHECK
                      - WIRE
                      - PAYPAL
                      - APPLE_PAY
                      - GOOGLE_PAY
                    example: CREDIT_CARD
                  cardLastFour:
                    type: string
                    description: Last four digits of payment card (PCI compliant)
                    example: '1234'
                  cardType:
                    type: string
                    description: Type of payment card
                    example: VISA
                  status:
                    type: string
                    description: Current payment status
                    enum:
                      - PENDING
                      - CONFIRMED
                      - FAILED
                      - CANCELLED
                      - REFUNDED
                    example: CONFIRMED
                  confirmationDate:
                    type: string
                    format: date-time
                    description: Date and time when payment was confirmed
                    example: '2024-01-15T10:30:00Z'
                  processorReference:
                    type: string
                    description: Payment processor reference ID
                    example: stripe_pi_1234567890
                  clientId:
                    type: integer
                    description: Associated client identifier
                    example: 789
                  clientName:
                    type: string
                    description: Name of the client who made the payment
                    example: Acme Corporation
                  invoiceId:
                    type: integer
                    description: Associated invoice identifier
                    example: 456
                  invoiceNumber:
                    type: string
                    description: Invoice number for the payment
                    example: INV-2024-001
                  createdAt:
                    type: string
                    format: date-time
                    description: Payment creation timestamp
                    example: '2024-01-15T10:25:00Z'
                  updatedAt:
                    type: string
                    format: date-time
                    description: Last update timestamp
                    example: '2024-01-15T10:30:00Z'
        '401':
          description: Unauthorized - Invalid or missing authentication token
        '403':
          description: Forbidden - Insufficient permissions to access this payment
        '404':
          description: Payment not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Payment not found
                  message:
                    type: string
                    example: Payment with ID 12345 does not exist
        '500':
          description: Internal server error
  /gql/v1/projects:
    post:
      tags:
        - Projects
      summary: List projects
      description: >
        **Retrieve all projects with basic pagination support**


        Projects are represented via `vw_job`. Default ordering by `updatedAt`
        desc.


        Real Example:

        ```bash

        curl --location 'https://{{host}}/v1/projects' \

        --header 'Authorization: bearer {{token}}' \

        --header 'Content-Type: application/json' \

        --data '{
          "pageSize": 25,
          "page": 0
        }'

        ```
      operationId: getProjectsPaginated
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                pageSize:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 50
                  description: Maximum number of projects to return
                page:
                  type: integer
                  minimum: 0
                  default: 0
                  description: Number of records to skip for pagination
            examples:
              default_pagination:
                summary: Default pagination
                value:
                  pageSize: 25
                  page: 0
      responses:
        '200':
          description: Successfully retrieved projects
        '400':
          description: Bad request - invalid pagination parameters
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /gql/v1/projects/search:
    post:
      tags:
        - Projects
      summary: Search projects
      description: >
        **Advanced project filtering with custom GraphQL where clauses and
        dynamic ordering**


        Projects are stored in the Jobs table (vw_job view). Supports manager,
        dates, and flags.


        Real Example:

        ```bash

        curl --location 'https://{{host}}/v1/projects/search' \

        --header 'Authorization: bearer {{token}}' \

        --header 'Content-Type: application/json' \

        --data '{
          "pageSize": 1,
          "where": {
            "_and": [
              {
                "_or": [
                  {
                    "name": {
                      "_ilike": "%migration%"
                    }
                  },
                  {
                    "serviceDescription": {
                      "_ilike": "%review%"
                    }
                  }
                ]
              },
              {
                "active": {
                  "_eq": true
                }
              },
              {
                "updatedAt": {
                  "_gte": "1900-01-01T00:00:00Z"
                }
              },
              {
                "partnerId": {
                  "_in": [
                    101,
                    102,
                    103
                  ]
                }
              }
            ]
          },
          "orderBy": [
            {
              "updatedAt": "desc"
            },
            {
              "name": "asc"
            }
          ]
        }'

        ```
      operationId: filterProjectsDynamic
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                pageSize:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 1
                where:
                  type: object
                  description: GraphQL-style where clause for complex project filtering
                  example:
                    _and:
                      - _or:
                          - name:
                              _ilike: '%migration%'
                          - serviceDescription:
                              _ilike: '%review%'
                      - active:
                          _eq: true
                      - updatedAt:
                          _gte: '1900-01-01T00:00:00Z'
                      - partnerId:
                          _in:
                            - 101
                            - 102
                            - 103
                orderBy:
                  type: array
                  items:
                    type: object
                  description: Dynamic ordering specifications
                  example:
                    - updatedAt: desc
                    - name: asc
      responses:
        '200':
          description: Successfully retrieved filtered projects
        '400':
          description: Bad request - invalid where/orderBy
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /gql/v1/project/{id}:
    get:
      tags:
        - Projects
      summary: Get project by ID
      description: |
        **Retrieve a specific project by its unique identifier**

        This endpoint provides detailed project information including:
        - Complete project details and specifications
        - Project status and lifecycle information
        - Client and engagement relationships
        - Team assignments and resource allocation
        - Budget and financial tracking data
        - Timeline and milestone information

        **Project Management Features:**
        - Project lifecycle tracking
        - Resource allocation and team management
        - Budget and financial oversight
        - Timeline and milestone management
        - Client relationship integration

        **Project Details Include:**
        - Project name and description
        - Project status and phase
        - Client and engagement references
        - Team member assignments
        - Budget and financial data
        - Timeline and milestone tracking

        **Business Applications:**
        - Project status monitoring
        - Resource allocation analysis
        - Budget tracking and reporting
        - Client project portfolio management
        - Team performance analysis

        **Real Example:**
        ```bash
        curl --location 'https://{{host}}/v1/project/67890' \
        --header 'Authorization: bearer {{token}}' \
        --header 'Content-Type: application/json'
        ```

        **Response Example:**
        ```json
        {
          "id": 67890,
          "name": "Q4 Financial Audit",
          "description": "Comprehensive financial audit for Q4 2024 including tax preparation and compliance review",
          "status": "IN_PROGRESS",
          "phase": "EXECUTION",
          "clientId": 789,
          "clientName": "Acme Corporation",
          "engagementId": 456,
          "engagementName": "Annual Audit Engagement",
          "startDate": "2024-10-01T00:00:00Z",
          "endDate": "2024-12-31T23:59:59Z",
          "budget": 25000.00,
          "currency": "USD",
          "actualCost": 18500.00,
          "teamMembers": [
            {
              "staffId": 123,
              "name": "John Smith",
              "role": "SENIOR_AUDITOR",
              "allocation": 0.8
            },
            {
              "staffId": 124,
              "name": "Jane Doe",
              "role": "AUDITOR",
              "allocation": 0.6
            }
          ],
          "milestones": [
            {
              "id": 1,
              "name": "Planning Phase Complete",
              "dueDate": "2024-10-15T00:00:00Z",
              "status": "COMPLETED"
            },
            {
              "id": 2,
              "name": "Fieldwork Complete",
              "dueDate": "2024-12-15T00:00:00Z",
              "status": "IN_PROGRESS"
            }
          ],
          "createdAt": "2024-09-15T10:00:00Z",
          "updatedAt": "2024-11-20T14:30:00Z"
        }
        ```
      operationId: getProjectById
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier of the project
          schema:
            type: integer
            minimum: 1
          example: 67890
      responses:
        '200':
          description: Project details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: Unique project identifier
                    example: 67890
                  name:
                    type: string
                    description: Project name
                    example: Q4 Financial Audit
                  description:
                    type: string
                    description: Detailed project description
                    example: >-
                      Comprehensive financial audit for Q4 2024 including tax
                      preparation and compliance review
                  status:
                    type: string
                    description: Current project status
                    enum:
                      - PLANNING
                      - IN_PROGRESS
                      - ON_HOLD
                      - COMPLETED
                      - CANCELLED
                    example: IN_PROGRESS
                  phase:
                    type: string
                    description: Current project phase
                    enum:
                      - PLANNING
                      - EXECUTION
                      - REVIEW
                      - DELIVERY
                      - CLOSED
                    example: EXECUTION
                  clientId:
                    type: integer
                    description: Associated client identifier
                    example: 789
                  clientName:
                    type: string
                    description: Name of the client
                    example: Acme Corporation
                  engagementId:
                    type: integer
                    description: Associated engagement identifier
                    example: 456
                  engagementName:
                    type: string
                    description: Name of the engagement
                    example: Annual Audit Engagement
                  startDate:
                    type: string
                    format: date-time
                    description: Project start date
                    example: '2024-10-01T00:00:00Z'
                  endDate:
                    type: string
                    format: date-time
                    description: Project end date
                    example: '2024-12-31T23:59:59Z'
                  budget:
                    type: number
                    format: decimal
                    description: Project budget amount
                    example: 25000
                  currency:
                    type: string
                    description: Budget currency code
                    example: USD
                  actualCost:
                    type: number
                    format: decimal
                    description: Actual cost incurred to date
                    example: 18500
                  teamMembers:
                    type: array
                    description: Team members assigned to the project
                    items:
                      type: object
                      properties:
                        staffId:
                          type: integer
                          description: Staff member identifier
                          example: 123
                        name:
                          type: string
                          description: Staff member name
                          example: John Smith
                        role:
                          type: string
                          description: Role on the project
                          enum:
                            - PROJECT_MANAGER
                            - SENIOR_AUDITOR
                            - AUDITOR
                            - ASSOCIATE
                            - INTERN
                          example: SENIOR_AUDITOR
                        allocation:
                          type: number
                          format: decimal
                          description: Time allocation percentage (0.0 to 1.0)
                          example: 0.8
                  milestones:
                    type: array
                    description: Project milestones
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Milestone identifier
                          example: 1
                        name:
                          type: string
                          description: Milestone name
                          example: Planning Phase Complete
                        dueDate:
                          type: string
                          format: date-time
                          description: Milestone due date
                          example: '2024-10-15T00:00:00Z'
                        status:
                          type: string
                          description: Milestone status
                          enum:
                            - NOT_STARTED
                            - IN_PROGRESS
                            - COMPLETED
                            - OVERDUE
                          example: COMPLETED
                  createdAt:
                    type: string
                    format: date-time
                    description: Project creation timestamp
                    example: '2024-09-15T10:00:00Z'
                  updatedAt:
                    type: string
                    format: date-time
                    description: Last update timestamp
                    example: '2024-11-20T14:30:00Z'
        '401':
          description: Unauthorized - Invalid or missing authentication token
        '403':
          description: Forbidden - Insufficient permissions to access this project
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Project not found
                  message:
                    type: string
                    example: Project with ID 67890 does not exist
        '500':
          description: Internal server error
  /gql/v1/wip:
    post:
      tags:
        - Time
      summary: List WIP entries
      description: >
        **Work in Progress tracking with comprehensive financial lifecycle
        management**


        This advanced endpoint provides complete WIP management including:

        - WIP value tracking from creation through billing completion

        - Outstanding balance calculations for unbilled work

        - Multi-dimensional analysis (client, job, date-based)

        - Financial aggregations for WIP reporting and analysis

        - Integration with client and job data for complete context


        **Financial Tracking Features:**

        - WIP value recording and outstanding balance calculation

        - Billed amount tracking for revenue recognition

        - Write-off amount management for uncollectible WIP

        - Job and client correlation for project profitability


        **WIP Lifecycle Management:**

        - Creation date logging for aging analysis

        - WIP type categorization (TIME, EXPENSE, FIXED_FEE, etc.)

        - Outstanding value calculation for billing preparation

        - Billed amount reconciliation for revenue tracking


        **Business Intelligence & Reporting:**

        - Client-specific WIP analysis and aging

        - Job-based profitability and WIP tracking

        - WIP aging reports for collections management

        - Revenue recognition and billing pipeline analysis


        **Financial Aggregations:**

        - Total WIP value across filtered records

        - Outstanding WIP calculations for billing preparation

        - Billed amount summaries for revenue analysis

        - Write-off tracking for financial reporting


        **Advanced Filtering:**

        - Client-specific WIP retrieval and analysis

        - Job-based WIP tracking for project management

        - Date range queries for period-specific reporting

        - WIP type filtering for category analysis


        **Real Example:**

        ```bash

        curl --location 'https://{{host}}/v1/wip' \

        --header 'Authorization: bearer {{token}} \

        --header 'Content-Type: application/json' \

        --data '{
          "pageSize": 25,
          "page": 0
        }'

        ```
      operationId: getWip
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                pageSize:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 25
                  description: Maximum number of WIP records to return
                  example: 25
                page:
                  type: integer
                  minimum: 0
                  default: 0
                  description: Page number for pagination (0-based)
                  example: 0
                clientId:
                  type: integer
                  description: Filter WIP records by specific client ID
                  example: 1561
                jobId:
                  type: integer
                  description: Filter WIP records by specific job ID
                  example: 2514
                wipType:
                  type: string
                  description: Filter by WIP type
                  enum:
                    - Time
                    - Expense
                    - Fixed_Fee
                    - Disbursement
                  example: Time
                startDate:
                  type: string
                  format: date-time
                  description: Start date for WIP logged date range filter
                  example: '2024-01-01T00:00:00'
                endDate:
                  type: string
                  format: date-time
                  description: End date for WIP logged date range filter
                  example: '2024-12-31T23:59:59'
                sortOrder:
                  type: string
                  enum:
                    - asc
                    - desc
                  default: desc
                  description: Sort order for logged date
                  example: desc
            examples:
              default_pagination:
                summary: Default pagination
                value:
                  pageSize: 25
                  page: 0
      responses:
        '200':
          description: Successfully retrieved WIP records with financial aggregations
          content:
            application/json:
              schema:
                type: object
                properties:
                  deid_wip:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Unique WIP record identifier
                          example: 850321
                        pmsRef:
                          type: string
                          description: Practice management system reference
                          example: '1789456'
                        wipType:
                          type: string
                          description: Type of WIP entry
                          example: Time
                        loggedDate:
                          type: string
                          format: date-time
                          description: Date when WIP was logged
                          example: '2024-01-17T05:00:00'
                        wipValue:
                          type: number
                          format: decimal
                          description: Original WIP value recorded
                          example: 1250
                        wipValueOutstanding:
                          type: number
                          format: decimal
                          description: Outstanding WIP value yet to be billed
                          example: 0
                        billedAmount:
                          type: number
                          format: decimal
                          description: Amount that has been billed from this WIP
                          example: 1225
                        writeOffAmount:
                          type: number
                          format: decimal
                          description: Amount written off as uncollectible
                          example: 25
                        notes:
                          type: string
                          nullable: true
                          description: Additional notes or description for the WIP entry
                          example: Consultation and analysis for Q1 financial review
                        clientId:
                          type: integer
                          description: Associated client identifier
                          example: 1561
                        jobId:
                          type: integer
                          description: Associated job identifier
                          example: 2514
                        createdAt:
                          type: string
                          format: date-time
                          description: WIP record creation timestamp
                          example: '2024-05-12T23:02:33.24516+00:00'
                        updatedAt:
                          type: string
                          format: date-time
                          description: WIP record last update timestamp
                          example: '2024-05-12T23:02:33.24516+00:00'
                        client:
                          type: object
                          description: Associated client information
                          properties:
                            id:
                              type: integer
                              example: 1561
                            name:
                              type: string
                              example: TechFlow Enterprises
                        job:
                          type: object
                          description: Associated job information
                          properties:
                            id:
                              type: integer
                              example: 2514
                            name:
                              type: string
                              example: Q1 Financial Review 2024
                  deid_wip_aggregate:
                    type: object
                    properties:
                      aggregate:
                        type: object
                        properties:
                          count:
                            type: integer
                            description: Total number of WIP records matching criteria
                            example: 84
                          sum:
                            type: object
                            properties:
                              wipValue:
                                type: number
                                format: decimal
                                description: Total WIP value across all matching records
                                example: 24186.15
                              billedAmount:
                                type: number
                                format: decimal
                                description: >-
                                  Total billed amount across all matching
                                  records
                                example: 19612.07
                              wipValueOutstanding:
                                type: number
                                format: decimal
                                description: Total outstanding WIP value
                                example: 0
              examples:
                successful_response:
                  summary: WIP records with financial tracking and aggregations
                  value:
                    deid_wip:
                      - id: 850321
                        pmsRef: '1789456'
                        wipType: Time
                        loggedDate: '2024-01-17T05:00:00'
                        wipValue: 1250
                        wipValueOutstanding: 0
                        billedAmount: 1225
                        writeOffAmount: 25
                        notes: Consultation and analysis for Q1 financial review
                        clientId: 1561
                        jobId: 2514
                        createdAt: '2024-05-12T23:02:33.24516+00:00'
                        updatedAt: '2024-05-12T23:02:33.24516+00:00'
                        client:
                          id: 1561
                          name: TechFlow Enterprises
                        job:
                          id: 2514
                          name: Q1 Financial Review 2024
                      - id: 850142
                        pmsRef: '1789123'
                        wipType: Expense
                        loggedDate: '2024-01-15T05:00:00'
                        wipValue: 350
                        wipValueOutstanding: 0
                        billedAmount: 343.5
                        writeOffAmount: 6.5
                        notes: null
                        clientId: 1561
                        jobId: 2514
                        createdAt: '2024-05-12T23:00:05.824148+00:00'
                        updatedAt: '2024-05-12T23:00:05.824148+00:00'
                        client:
                          id: 1561
                          name: TechFlow Enterprises
                        job:
                          id: 2514
                          name: Q1 Financial Review 2024
                      - id: 849987
                        pmsRef: '1788890'
                        wipType: Time
                        loggedDate: '2024-01-12T05:00:00'
                        wipValue: 875
                        wipValueOutstanding: 125
                        billedAmount: 750
                        writeOffAmount: 0
                        notes: Document review and preparation
                        clientId: 1561
                        jobId: 2514
                        createdAt: '2024-05-12T23:00:07.784813+00:00'
                        updatedAt: '2024-05-12T23:00:07.784813+00:00'
                        client:
                          id: 1561
                          name: TechFlow Enterprises
                        job:
                          id: 2514
                          name: Q1 Financial Review 2024
                    deid_wip_aggregate:
                      aggregate:
                        count: 84
                        sum:
                          wipValue: 24186.15
                          billedAmount: 19612.07
                          wipValueOutstanding: 125
                real_api_response:
                  summary: Sample from actual API response
                  value:
                    deid_wip:
                      - id: 743292
                        pmsRef: '1694524'
                        wipType: Time
                        loggedDate: '2018-01-17T05:00:00'
                        wipValue: 127.5
                        wipValueOutstanding: 0
                        billedAmount: 0
                        writeOffAmount: 127.5
                        notes: >-
                          Velit aut provident sint dolorum eaque necessitatibus
                          dicta reprehenderit eveniet dolore eius neque est.
                        clientId: 1561
                        jobId: 2514
                        createdAt: '2023-05-12T23:02:33.24516+00:00'
                        updatedAt: '2023-05-12T23:02:33.24516+00:00'
                        client:
                          id: 1561
                          name: Cammie Cremin
                        job:
                          id: 2514
                          name: Justin Case
                      - id: 510044
                        pmsRef: '1159387'
                        wipType: Time
                        loggedDate: '2016-03-23T04:00:00'
                        wipValue: 87.5
                        wipValueOutstanding: 0
                        billedAmount: 86.05
                        writeOffAmount: 1.45
                        notes: null
                        clientId: 1561
                        jobId: 2514
                        createdAt: '2023-05-12T23:00:05.824148+00:00'
                        updatedAt: '2023-05-12T23:00:05.824148+00:00'
                        client:
                          id: 1561
                          name: Cammie Cremin
                        job:
                          id: 2514
                          name: Justin Case
                    deid_wip_aggregate:
                      aggregate:
                        count: 84
                        sum:
                          wipValue: 24186.15
                          billedAmount: 19612.07
                          wipValueOutstanding: 0
                empty_response:
                  summary: No WIP records found
                  value:
                    deid_wip: []
                    deid_wip_aggregate:
                      aggregate:
                        count: 0
                        sum:
                          wipValue: 0
                          billedAmount: 0
                          wipValueOutstanding: 0
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              examples:
                invalid_date_range:
                  summary: Invalid date range
                  value:
                    error: startDate must be before or equal to endDate
                    code: INVALID_DATE_RANGE
                invalid_client_id:
                  summary: Invalid client ID
                  value:
                    error: clientId must be a positive integer
                    code: INVALID_CLIENT_ID
        '401':
          description: Unauthorized - missing or invalid admin secret
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              examples:
                missing_auth:
                  summary: Missing authentication header
                  value:
                    error: x-hasura-admin-secret header is required
                    code: MISSING_AUTH_HEADER
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
  /gql/v1/wips/search:
    post:
      tags:
        - Time
      summary: Search WIP entries
      description: >
        **Advanced WIP filtering with custom GraphQL where clauses and dynamic
        ordering**


        Supports wipType selection, date ranges, and client/job constraints.


        Real Example:

        ```bash

        curl --location 'https://{{host}}/v1/wips/search' \

        --header 'Authorization: bearer {{token}}' \

        --header 'Content-Type: application/json' \

        --data '{
          "pageSize": 1,
          "where": {
            "_and": [
              {
                "_or": [
                  {
                    "type": {
                      "_in": ["TIME", "EXPENSE"]
                    }
                  },
                  {
                    "notes": {
                      "_ilike": "%consultation%"
                    }
                  }
                ]
              },
              {
                "approved": {
                  "_eq": true
                }
              },
              {
                "loggedDate": {
                  "_gte": "1900-01-01T00:00:00Z"
                }
              },
              {
                "clientId": {
                  "_in": [
                    1001,
                    1002,
                    1003
                  ]
                }
              }
            ]
          },
          "orderBy": [
            {
              "loggedDate": "desc"
            },
            {
              "value": "desc"
            }
          ]
        }'

        ```
      operationId: filterWipsDynamic
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                pageSize:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 1
                where:
                  type: object
                  description: GraphQL-style where clause for complex WIP filtering
                  example:
                    _and:
                      - _or:
                          - type:
                              _in:
                                - TIME
                                - EXPENSE
                          - notes:
                              _ilike: '%consultation%'
                      - approved:
                          _eq: true
                      - loggedDate:
                          _gte: '1900-01-01T00:00:00Z'
                      - clientId:
                          _in:
                            - 1001
                            - 1002
                            - 1003
                orderBy:
                  type: array
                  items:
                    type: object
                  description: Dynamic ordering specifications
                  example:
                    - loggedDate: desc
                    - value: desc
      responses:
        '200':
          description: Successfully retrieved filtered WIP entries
        '400':
          description: Bad request - invalid where/orderBy
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /gql/v1/wip/{id}:
    get:
      tags:
        - Time
      summary: Get WIP time entry by ID
      description: >
        **Retrieve a specific work-in-progress (WIP) time entry by its unique
        identifier**


        This endpoint provides detailed WIP time entry information including:

        - Complete time entry details and descriptions

        - Time entry status and approval information

        - Client, project, and task relationships

        - Billable and non-billable time tracking

        - Rate calculations and billing preparation

        - Time entry history and modifications


        **WIP Time Management Features:**

        - Time entry lifecycle tracking

        - Billable vs non-billable time classification

        - Rate calculation and billing preparation

        - Project and task relationship management

        - Approval workflow integration


        **WIP Time Details Include:**

        - Time entry description and details

        - Time entry status and type

        - Client, project, and task information

        - Time duration and rates

        - Billable calculations

        - Approval status


        **Business Applications:**

        - Time entry review and approval

        - Billable time calculation

        - Project time tracking

        - Client billing preparation

        - Productivity analysis


        **Real Example:**

        ```bash

        curl --location 'https://{{host}}/v1/wip/89012' \

        --header 'Authorization: bearer {{token}}' \

        --header 'Content-Type: application/json'

        ```


        **Response Example:**

        ```json

        {
          "id": 89012,
          "description": "Financial statement review and analysis",
          "status": "PENDING_APPROVAL",
          "type": "BILLABLE",
          "staffId": 123,
          "staffName": "John Smith",
          "clientId": 789,
          "clientName": "Acme Corporation",
          "projectId": 67890,
          "projectName": "Q4 Financial Audit",
          "taskId": 456,
          "taskName": "Financial Statement Review",
          "date": "2024-11-20T00:00:00Z",
          "startTime": "2024-11-20T09:00:00Z",
          "endTime": "2024-11-20T17:00:00Z",
          "duration": 8.0,
          "billableHours": 8.0,
          "nonBillableHours": 0.0,
          "hourlyRate": 250.00,
          "billableAmount": 2000.00,
          "currency": "USD",
          "notes": "Completed comprehensive review of Q4 financial statements including variance analysis",
          "approvalHistory": [
            {
              "id": 1,
              "approverId": 124,
              "approverName": "Jane Doe",
              "approvalDate": "2024-11-21T10:30:00Z",
              "status": "PENDING",
              "comments": "Under review"
            }
          ],
          "createdAt": "2024-11-20T17:30:00Z",
          "updatedAt": "2024-11-21T10:30:00Z"
        }

        ```
      operationId: getWipById
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier of the WIP time entry
          schema:
            type: integer
            minimum: 1
          example: 89012
      responses:
        '200':
          description: WIP time entry details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: Unique WIP time entry identifier
                    example: 89012
                  description:
                    type: string
                    description: Time entry description
                    example: Financial statement review and analysis
                  status:
                    type: string
                    description: Time entry status
                    enum:
                      - DRAFT
                      - SUBMITTED
                      - PENDING_APPROVAL
                      - APPROVED
                      - REJECTED
                      - BILLED
                    example: PENDING_APPROVAL
                  type:
                    type: string
                    description: Time entry type
                    enum:
                      - BILLABLE
                      - NON_BILLABLE
                      - PTO
                      - TRAINING
                      - ADMINISTRATIVE
                    example: BILLABLE
                  staffId:
                    type: integer
                    description: Staff member identifier
                    example: 123
                  staffName:
                    type: string
                    description: Staff member name
                    example: John Smith
                  clientId:
                    type: integer
                    description: Associated client identifier
                    example: 789
                  clientName:
                    type: string
                    description: Client name
                    example: Acme Corporation
                  projectId:
                    type: integer
                    description: Associated project identifier
                    example: 67890
                  projectName:
                    type: string
                    description: Project name
                    example: Q4 Financial Audit
                  taskId:
                    type: integer
                    description: Associated task identifier
                    example: 456
                  taskName:
                    type: string
                    description: Task name
                    example: Financial Statement Review
                  date:
                    type: string
                    format: date
                    description: Date of time entry
                    example: '2024-11-20T00:00:00Z'
                  startTime:
                    type: string
                    format: date-time
                    description: Start time of work
                    example: '2024-11-20T09:00:00Z'
                  endTime:
                    type: string
                    format: date-time
                    description: End time of work
                    example: '2024-11-20T17:00:00Z'
                  duration:
                    type: number
                    format: decimal
                    description: Total duration in hours
                    example: 8
                  billableHours:
                    type: number
                    format: decimal
                    description: Billable hours
                    example: 8
                  nonBillableHours:
                    type: number
                    format: decimal
                    description: Non-billable hours
                    example: 0
                  hourlyRate:
                    type: number
                    format: decimal
                    description: Hourly rate for this time entry
                    example: 250
                  billableAmount:
                    type: number
                    format: decimal
                    description: Total billable amount
                    example: 2000
                  currency:
                    type: string
                    description: Currency code
                    example: USD
                  notes:
                    type: string
                    description: Additional notes about the time entry
                    example: >-
                      Completed comprehensive review of Q4 financial statements
                      including variance analysis
                  approvalHistory:
                    type: array
                    description: Approval history for this time entry
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Approval record identifier
                          example: 1
                        approverId:
                          type: integer
                          description: Approver identifier
                          example: 124
                        approverName:
                          type: string
                          description: Approver name
                          example: Jane Doe
                        approvalDate:
                          type: string
                          format: date-time
                          description: Approval date
                          example: '2024-11-21T10:30:00Z'
                        status:
                          type: string
                          description: Approval status
                          enum:
                            - PENDING
                            - APPROVED
                            - REJECTED
                            - COMMENTS
                          example: PENDING
                        comments:
                          type: string
                          description: Approval comments
                          example: Under review
                  createdAt:
                    type: string
                    format: date-time
                    description: Time entry creation timestamp
                    example: '2024-11-20T17:30:00Z'
                  updatedAt:
                    type: string
                    format: date-time
                    description: Last update timestamp
                    example: '2024-11-21T10:30:00Z'
        '401':
          description: Unauthorized - Invalid or missing authentication token
        '403':
          description: Forbidden - Insufficient permissions to access this WIP time entry
        '404':
          description: WIP time entry not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: WIP time entry not found
                  message:
                    type: string
                    example: WIP time entry with ID 89012 does not exist
        '500':
          description: Internal server error
components:
  schemas:
    Error:
      type: object
      description: Standard error response format
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: Human-readable error message
          example: Invalid parameter value
        code:
          type: string
          description: Machine-readable error code
          example: INVALID_PARAMETER
        details:
          type: string
          description: Additional error context
          example: The 'pageSize' parameter must be between 1 and 1000
    DraftInvoiceHistory:
      type: object
      description: Draft invoice history record with client and draft invoice details
      properties:
        clientId:
          type: integer
          description: Client identifier
          example: 7720
        invoiceId:
          type: integer
          description: Invoice identifier
          example: 125890
        jobId:
          type: integer
          description: Associated job/project identifier
          example: 2514
        client:
          type: object
          description: Client summary information
          properties:
            active:
              type: boolean
              example: true
            clientRef:
              type: string
              example: TF-2024-789
            name:
              type: string
              example: TechFlow Enterprises
            pmsRef:
              type: string
              example: '240815'
        draftInvoice:
          type: object
          description: Draft invoice metadata
          properties:
            approvedAt:
              type: string
              format: date-time
              example: '2024-03-15T14:32:18+00:00'
            arTranId:
              type: integer
              example: 125890
            approverStaffId:
              type: integer
              example: 301
            approvedByStaffId:
              type: integer
              example: 301
            invoiceId:
              type: integer
              example: 125890
            isActive:
              type: boolean
              example: true
            pms_invoice_number:
              type: string
              example: INV-2024-4850
            status:
              type: string
              example: APPROVED
    DraftInvoiceHistoryListResponse:
      type: object
      description: Standard response format for draft invoice history endpoints
      properties:
        draftInvoices:
          type: array
          items:
            $ref: '#/components/schemas/DraftInvoiceHistory'
        total:
          type: object
          properties:
            aggregate:
              type: object
              properties:
                count:
                  type: integer
                  description: >-
                    Total number of draft invoice history records matching
                    criteria
                  example: 94
    ClientContactInfo:
      type: object
      description: Client contact information details
      properties:
        id:
          type: integer
          example: 9957
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Doe
        email:
          type: string
          format: email
          example: loree.kling@yahoo.com
        phone:
          type: string
          example: 1-555-123-4567
        address:
          type: string
          example: 123 Main Street
        city:
          type: string
          example: Anytown
        state:
          type: string
          example: CA
        zip_code:
          type: string
          example: '12345'
    StaffMember:
      type: object
      description: Staff member basic information
      properties:
        id:
          type: integer
          example: 53
        firstName:
          type: string
          example: Allen
        lastName:
          type: string
          example: Hermiston
        email:
          type: string
          format: email
          example: allen.hermiston@company.com
    Client:
      type: object
      description: Complete client record with all associated data
      properties:
        id:
          type: integer
          description: Unique client identifier
          example: 2180
        pmsRef:
          type: string
          description: Practice Management System reference
          example: '1155'
        clientRef:
          type: string
          description: External client reference number
          example: '41664'
        name:
          type: string
          description: Client full name or company name
          example: Aaron Fahey
        clientKey:
          type: string
          description: Formatted client key with padding
          example: 000000041664                              f
        active:
          type: boolean
          description: Client active status
          example: true
        partnerStaffId:
          type: integer
          description: ID of assigned partner staff member
          example: 53
        managerStaffId:
          type: integer
          description: ID of assigned manager staff member
          example: 19
        createdAt:
          type: string
          format: date-time
          description: Client record creation timestamp
          example: '2023-05-12T22:43:55.488054+00:00'
        updatedAt:
          type: string
          format: date-time
          description: Last modification timestamp
          example: '2023-06-09T21:34:28.817274+00:00'
        clientContactInfo:
          $ref: '#/components/schemas/ClientContactInfo'
        partnerStaff:
          $ref: '#/components/schemas/StaffMember'
        managerStaff:
          $ref: '#/components/schemas/StaffMember'
    ClientWithNumber:
      type: object
      description: Client details with number field
      properties:
        id:
          type: integer
          example: 420
        name:
          type: string
          example: TechFlow Enterprises
        number:
          type: string
          example: '52150'
    Engagement:
      type: object
      description: Project engagement record with staff assignments
      properties:
        id:
          type: integer
          description: Unique engagement identifier
          example: 8
        name:
          type: string
          description: Generated engagement name from template
          example: 2024 Annual Review and Tax 52150
        start_dt:
          type: string
          format: date
          description: Engagement start date
          example: '2024-03-15'
        end_dt:
          type: string
          format: date
          description: Engagement end date
          example: '2024-04-30'
        status:
          type: string
          description: Current engagement status
          example: EXECUTED
        client_id:
          type: integer
          description: Associated client identifier
          example: 420
        partner_staff_id:
          type: integer
          description: Partner staff member assigned to engagement
          example: 53
        manager_staff_id:
          type: integer
          description: Manager staff member assigned to engagement
          example: 15
        created_at:
          type: string
          format: date-time
          description: Engagement record creation timestamp
          example: '2024-03-14T10:58:38.605333+00:00'
        updated_at:
          type: string
          format: date-time
          description: Engagement record last update timestamp
          example: '2024-07-27T00:08:05.822177+00:00'
        engagement_name_template:
          type: string
          description: Template used to generate engagement name
          example: '{{fiscal_year.year}} {{letter_template.name}} {{client.number}}'
        client:
          $ref: '#/components/schemas/ClientWithNumber'
        partnerStaff:
          $ref: '#/components/schemas/StaffMember'
        managerStaff:
          $ref: '#/components/schemas/StaffMember'
    Department:
      type: object
      description: Department information
      properties:
        id:
          type: integer
          example: 7
        name:
          type: string
          example: Technology
    StaffType:
      type: object
      description: Staff type classification details
      properties:
        id:
          type: integer
          example: 11
        description:
          type: string
          example: Senior Associate
    ClientBasic:
      type: object
      description: Basic client information for relationships
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: TechFlow Enterprises
    CreditLabel:
      type: object
      description: Credit label details for categorization
      properties:
        id:
          type: integer
          example: 3
        name:
          type: string
          example: Service Credit
        description:
          type: string
          example: Credit for service issues or complaints
    DebitLabel:
      type: object
      description: Debit label details for categorization
      properties:
        id:
          type: integer
          example: 2
        name:
          type: string
          example: Late Fee
        description:
          type: string
          example: Late payment penalty charge
        is_active:
          type: boolean
          example: true
    ARTransactionBasic:
      type: object
      description: Basic AR transaction details for invoice relationships
      properties:
        id:
          type: integer
          example: 125890
        pmsRef:
          type: string
          description: Practice management system reference
          example: '240815'
        transactionDate:
          type: string
          format: date-time
          description: Transaction date
          example: '2024-03-22T05:00:00'
        amount:
          type: number
          format: decimal
          description: Transaction amount
          example: 4250
        allocated:
          type: number
          format: decimal
          description: Allocated amount
          example: 4250
        clientId:
          type: integer
          description: Client identifier
          example: 7720
        client:
          $ref: '#/components/schemas/ClientBasic'
    ClientWithRef:
      type: object
      description: Client information with reference number
      properties:
        id:
          type: integer
          example: 789
        name:
          type: string
          example: TechFlow Enterprises
        clientRef:
          type: string
          example: TF-2024-789
    Job:
      type: object
      description: Job information for WIP tracking
      properties:
        id:
          type: integer
          example: 2514
        name:
          type: string
          example: Q1 Financial Review 2024
    PaginationRequest:
      type: object
      description: Standard pagination parameters
      properties:
        pageSize:
          type: integer
          minimum: 1
          maximum: 1000
          default: 50
          description: Maximum number of records to return
          example: 25
        page:
          type: integer
          minimum: 0
          default: 0
          description: Number of records to skip for pagination navigation
          example: 0
    AggregateCount:
      type: object
      description: Standard count aggregation
      properties:
        aggregate:
          type: object
          properties:
            count:
              type: integer
              description: Total number of records matching criteria
              example: 13697
    ARTransaction:
      type: object
      description: Accounts receivable transaction record
      properties:
        id:
          type: integer
          description: Unique transaction identifier
          example: 125001
        pmsRef:
          type: string
          description: Practice management system reference number
          example: '240815'
        type:
          type: string
          description: Transaction type classification
          example: Receipt
        transactionDate:
          type: string
          format: date-time
          description: Date when transaction occurred
          example: '2024-02-15T05:00:00'
        amount:
          type: number
          format: decimal
          description: Transaction amount (negative for receipts/credits)
          example: -1250
        allocated:
          type: number
          format: decimal
          description: Amount allocated/applied to invoices
          example: -1250
        notes:
          type: string
          description: Additional transaction notes or comments
          example: null
        clientId:
          type: integer
          description: Associated client identifier
          example: 1
        createdAt:
          type: string
          format: date-time
          description: Record creation timestamp
          example: '2024-05-12T22:50:18.418236+00:00'
        updatedAt:
          type: string
          format: date-time
          description: Record last update timestamp
          example: '2024-05-12T22:50:18.418236+00:00'
        client:
          $ref: '#/components/schemas/ClientBasic'
    AggregateCountSum:
      type: object
      description: Count and sum aggregation for financial data
      properties:
        aggregate:
          type: object
          properties:
            count:
              type: integer
              description: Total number of records matching criteria
              example: 48
            sum:
              type: object
              properties:
                amount:
                  type: number
                  format: decimal
                  description: Sum of amounts
                  example: -52750
                allocated:
                  type: number
                  format: decimal
                  description: Sum of allocated amounts
                  example: -52750
    Credit:
      type: object
      description: Credit entry with categorization
      properties:
        ar_tran_id:
          type: integer
          description: Associated AR transaction identifier
          example: 125890
        is_partial:
          type: boolean
          description: Whether this is a partial credit (true) or full credit (false)
          example: false
        credit_label_id:
          type: integer
          description: Reference to credit categorization label
          example: 3
        created_at:
          type: string
          format: date-time
          description: Credit record creation timestamp
          example: '2024-05-12T22:50:21.31979+00:00'
        updated_at:
          type: string
          format: date-time
          description: Credit record last update timestamp
          example: '2024-05-12T22:50:21.31979+00:00'
        creditLabel:
          $ref: '#/components/schemas/CreditLabel'
    Debit:
      type: object
      description: Debit entry with categorization and staff tracking
      properties:
        ar_tran_id:
          type: integer
          description: Associated AR transaction identifier
          example: 125890
        debit_label_id:
          type: integer
          description: Reference to debit categorization label
          example: 2
        created_at:
          type: string
          format: date-time
          description: Debit record creation timestamp
          example: '2024-05-12T22:50:21.31979+00:00'
        updated_at:
          type: string
          format: date-time
          description: Debit record last update timestamp
          example: '2024-05-12T22:50:21.31979+00:00'
        created_by_staff_id:
          type: integer
          description: ID of staff member who created the debit
          example: 15
        last_updated_by_staff_id:
          type: integer
          description: ID of staff member who last updated the debit
          example: 15
        custom_field_values:
          type: object
          description: Additional custom field data in JSON format
          example:
            reason: Late payment fee
            approved_by: manager
        debitLabel:
          $ref: '#/components/schemas/DebitLabel'
        createdByStaff:
          $ref: '#/components/schemas/StaffMember'
        lastUpdatedByStaff:
          $ref: '#/components/schemas/StaffMember'
    Invoice:
      type: object
      description: Invoice record with AR transaction details
      properties:
        arTranId:
          type: integer
          description: Associated AR transaction identifier
          example: 125890
        invoiceNumber:
          type: string
          description: Unique invoice number for client reference
          example: INV-2024-4850
        dueDate:
          type: string
          format: date-time
          description: Invoice payment due date
          example: '2024-04-24T05:00:00'
        status:
          type: string
          description: Current invoice status
          example: POSTED
        tax:
          type: number
          format: decimal
          description: Tax amount charged on invoice
          example: 0
        interest:
          type: number
          format: decimal
          description: Interest charges applied to invoice
          example: 0
        description:
          type: string
          description: Additional invoice description or notes
          example: null
        createdAt:
          type: string
          format: date-time
          description: Invoice record creation timestamp
          example: '2024-05-12T22:50:20.595961+00:00'
        updatedAt:
          type: string
          format: date-time
          description: Invoice record last update timestamp
          example: '2024-05-12T22:50:20.595961+00:00'
        ar_tran:
          $ref: '#/components/schemas/ARTransactionBasic'
    Payment:
      type: object
      description: Payment record with security compliance
      properties:
        id:
          type: integer
          description: Unique payment identifier
          example: 45201
        arTranId:
          type: integer
          description: Associated AR transaction identifier
          example: 125890
        paymentMethod:
          type: string
          description: Payment method type
          example: CREDIT_CARD
        amount:
          type: number
          format: decimal
          description: Payment amount
          example: 2750
        paymentDate:
          type: string
          format: date-time
          description: Date when payment was processed
          example: '2024-03-15T14:30:22+00:00'
        confirmationDate:
          type: string
          format: date-time
          description: Date when payment was confirmed
          example: '2024-03-15T14:32:18+00:00'
        status:
          type: string
          description: Current payment status
          example: CONFIRMED
        processorId:
          type: string
          description: Payment processor identifier
          example: stripe
        processorReferenceId:
          type: string
          description: Payment processor transaction reference
          example: pi_3N1K2mL4uZ5v6w7x8y9z0a1b
        last4Digits:
          type: string
          description: Last 4 digits of card (PCI compliant)
          example: '4242'
        cardType:
          type: string
          description: Credit card type
          example: VISA
        currency:
          type: string
          description: Payment currency code
          example: USD
        clientId:
          type: integer
          description: Associated client identifier
          example: 789
        createdAt:
          type: string
          format: date-time
          description: Payment record creation timestamp
          example: '2024-03-15T14:30:22.123456+00:00'
        updatedAt:
          type: string
          format: date-time
          description: Payment record last update timestamp
          example: '2024-03-15T14:32:18.789012+00:00'
        client:
          $ref: '#/components/schemas/ClientWithRef'
        ar_tran:
          $ref: '#/components/schemas/ARTransactionBasic'
    StaffComplete:
      type: object
      description: Complete staff record with department and type information
      properties:
        id:
          type: integer
          description: Unique staff identifier
          example: 301
        pmsRef:
          type: string
          description: Practice management system reference
          example: '2650'
        staffRef:
          type: string
          description: Staff reference code or initials
          example: JDM
        firstName:
          type: string
          description: Employee first name
          example: Sarah
        lastName:
          type: string
          description: Employee last name
          example: Johnson
        email:
          type: string
          description: Employee email address
          example: sarah.johnson@company.com
        active:
          type: boolean
          description: Employee active status
          example: true
        deptId:
          type: integer
          description: Department identifier
          example: 7
        staffTypeId:
          type: integer
          description: Staff type classification identifier
          example: 11
        createdAt:
          type: string
          format: date-time
          description: Staff record creation timestamp
          example: '2024-05-12T22:42:02.719873+00:00'
        updatedAt:
          type: string
          format: date-time
          description: Staff record last update timestamp
          example: '2024-05-12T22:42:05.487898+00:00'
        department:
          $ref: '#/components/schemas/Department'
        staff_type:
          $ref: '#/components/schemas/StaffType'
    WIP:
      type: object
      description: Work in Progress record with financial tracking
      properties:
        id:
          type: integer
          description: Unique WIP record identifier
          example: 850321
        pmsRef:
          type: string
          description: Practice management system reference
          example: '1789456'
        wipType:
          type: string
          description: Type of WIP entry
          example: Time
        loggedDate:
          type: string
          format: date-time
          description: Date when WIP was logged
          example: '2024-01-17T05:00:00'
        wipValue:
          type: number
          format: decimal
          description: Original WIP value recorded
          example: 1250
        wipValueOutstanding:
          type: number
          format: decimal
          description: Outstanding WIP value yet to be billed
          example: 0
        billedAmount:
          type: number
          format: decimal
          description: Amount that has been billed from this WIP
          example: 1225
        writeOffAmount:
          type: number
          format: decimal
          description: Amount written off as uncollectible
          example: 25
        notes:
          type: string
          description: Additional notes or description for the WIP entry
          example: Consultation and analysis for Q1 financial review
        clientId:
          type: integer
          description: Associated client identifier
          example: 1561
        jobId:
          type: integer
          description: Associated job identifier
          example: 2514
        createdAt:
          type: string
          format: date-time
          description: WIP record creation timestamp
          example: '2024-05-12T23:02:33.24516+00:00'
        updatedAt:
          type: string
          format: date-time
          description: WIP record last update timestamp
          example: '2024-05-12T23:02:33.24516+00:00'
        client:
          $ref: '#/components/schemas/ClientBasic'
        job:
          $ref: '#/components/schemas/Job'
    WIPAggregate:
      type: object
      description: WIP-specific aggregation with financial summaries
      properties:
        aggregate:
          type: object
          properties:
            count:
              type: integer
              description: Total number of WIP records
              example: 84
            sum:
              type: object
              properties:
                wipValue:
                  type: number
                  format: decimal
                  description: Total WIP value
                  example: 24186.15
                billedAmount:
                  type: number
                  format: decimal
                  description: Total billed amount
                  example: 19612.07
                wipValueOutstanding:
                  type: number
                  format: decimal
                  description: Total outstanding WIP value
                  example: 125
    Contact:
      type: object
      description: Contact record with contact info and client relationships
      properties:
        id:
          type: integer
          example: 1001
        pms_ref:
          type: string
          example: C-4451
        active:
          type: boolean
          example: true
        contact_info_id:
          type: integer
          example: 7001
        office_id:
          type: integer
          example: 3
        staff_id:
          type: integer
          example: 53
        type:
          type: string
          example: Billing
        fwd_email_confirmation:
          type: boolean
          example: false
        contact_info:
          $ref: '#/components/schemas/ClientContactInfo'
        contact_clients:
          type: array
          description: Relationships linking this contact to clients
          items:
            type: object
            properties:
              client_id:
                type: integer
                example: 2180
              contact_id:
                type: integer
                example: 1001
              pms_ref:
                type: string
                example: LL-9981
              active:
                type: boolean
                example: true
              client:
                type: object
                properties:
                  id:
                    type: integer
                    example: 2180
                  name:
                    type: string
                    example: TechFlow Enterprises
                  clientRef:
                    type: string
                    example: TF-2024-789
                  active:
                    type: boolean
                    example: true
    Project:
      type: object
      description: Project record from vw_job with status, client and staff references
      properties:
        id:
          type: integer
          example: 5012
        name:
          type: string
          example: Q1 Financial Review 2024
        startDate:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00Z'
        targetEndDate:
          type: string
          format: date-time
          example: '2024-03-31T23:59:59Z'
        dueDate:
          type: string
          format: date-time
          example: '2024-03-15T00:00:00Z'
        targetStartDate:
          type: string
          format: date-time
          example: '2023-12-01T00:00:00Z'
        pmsRef:
          type: string
          example: JOB-2024-115
        isCreatedByAiwyn:
          type: boolean
          example: true
        managerStaffId:
          type: integer
          example: 102
        partnerStaffId:
          type: integer
          example: 101
        status:
          type: string
          example: ACTIVE
        updatedAt:
          type: string
          format: date-time
          example: '2024-05-20T12:34:56.123456+00:00'
        sysRefs:
          type: object
        jobStatus:
          type: object
          properties:
            id:
              type: integer
              example: 4
            name:
              type: string
              example: In Progress
            state:
              type: string
              example: ACTIVE
        client:
          type: object
          properties:
            id:
              type: integer
              example: 2180
            name:
              type: string
              example: TechFlow Enterprises
            clientRef:
              type: string
              example: TF-2024-789
            clientGroup:
              type: object
              properties:
                id:
                  type: integer
                  example: 12
                name:
                  type: string
                  example: Enterprise
        managerStaff:
          $ref: '#/components/schemas/StaffMember'
        partnerStaff:
          $ref: '#/components/schemas/StaffMember'
    StaffUserTask:
      type: object
      description: Staff user task from vw_my_task with task type and job info
      properties:
        id:
          type: integer
          example: 88015
        taskType:
          type: object
          properties:
            code:
              type: string
              example: BILLABLE
            id:
              type: integer
              example: 12
            display:
              type: string
              example: Billable Work
            billable:
              type: boolean
              example: true
            updatedAt:
              type: string
              format: date-time
              example: '2024-05-10T09:10:11.000000+00:00'
            createdAt:
              type: string
              format: date-time
              example: '2023-05-10T09:10:11.000000+00:00'
            isManagedByAiwyn:
              type: boolean
              example: true
            rate_type:
              type: object
              properties:
                id:
                  type: integer
                  example: 3
                name:
                  type: string
                  example: Hourly
                createdAt:
                  type: string
                  format: date-time
                  example: '2020-01-01T00:00:00+00:00'
                updatedAt:
                  type: string
                  format: date-time
                  example: '2020-01-01T00:00:00+00:00'
            task_type_category:
              type: object
              properties:
                id:
                  type: integer
                  example: 2
                name:
                  type: string
                  example: Consulting
                description:
                  type: string
                  example: Client-facing consulting tasks
                associatedTaskTypes:
                  type: array
                  items:
                    type: integer
                  example:
                    - 11
                    - 12
                    - 13
                createdAt:
                  type: string
                  format: date-time
                  example: '2020-01-01T00:00:00+00:00'
                updatedAt:
                  type: string
                  format: date-time
                  example: '2020-01-01T00:00:00+00:00'
            job_templates:
              type: object
              properties:
                aggregate:
                  type: object
                  properties:
                    count:
                      type: integer
                      example: 5
        job:
          type: object
          description: Project information for the task
          properties:
            id:
              type: integer
              example: 5012
            name:
              type: string
              example: Q1 Financial Review 2024
            client:
              type: object
              properties:
                id:
                  type: integer
                  example: 2180
                name:
                  type: string
                  example: TechFlow Enterprises
                clientRef:
                  type: string
                  example: TF-2024-789
    FilterRequest:
      allOf:
        - $ref: '#/components/schemas/PaginationRequest'
        - type: object
          properties:
            where:
              type: object
              description: GraphQL-style boolean expression for filtering
              additionalProperties: true
              example:
                _and:
                  - active:
                      _eq: true
                  - name:
                      _ilike: '%searchterm%'
            orderBy:
              type: array
              description: Array of sorting criteria
              items:
                type: object
                additionalProperties: true
              example:
                - name: asc
                - createdAt: desc
    ClientListResponse:
      type: object
      description: Standard response format for client list endpoints
      properties:
        clients:
          type: array
          items:
            $ref: '#/components/schemas/Client'
        total:
          $ref: '#/components/schemas/AggregateCount'
    ARTransactionListResponse:
      type: object
      description: Standard response format for AR transaction endpoints
      properties:
        deid_ar_tran:
          type: array
          items:
            $ref: '#/components/schemas/ARTransaction'
        deid_ar_tran_aggregate:
          $ref: '#/components/schemas/AggregateCountSum'
    CreditListResponse:
      type: object
      description: Standard response format for credit endpoints
      properties:
        deid_credit:
          type: array
          items:
            $ref: '#/components/schemas/Credit'
        deid_credit_aggregate:
          $ref: '#/components/schemas/AggregateCount'
    DebitListResponse:
      type: object
      description: Standard response format for debit endpoints
      properties:
        deid_debit:
          type: array
          items:
            $ref: '#/components/schemas/Debit'
        deid_debit_aggregate:
          $ref: '#/components/schemas/AggregateCount'
    EngagementListResponse:
      type: object
      description: Standard response format for engagement endpoints
      properties:
        deid_engagement:
          type: array
          items:
            $ref: '#/components/schemas/Engagement'
        deid_engagement_aggregate:
          $ref: '#/components/schemas/AggregateCount'
    InvoiceListResponse:
      type: object
      description: Standard response format for invoice endpoints
      properties:
        deid_invoice:
          type: array
          items:
            $ref: '#/components/schemas/Invoice'
        deid_invoice_aggregate:
          $ref: '#/components/schemas/AggregateCount'
    PaymentListResponse:
      type: object
      description: Standard response format for payment endpoints
      properties:
        deid_payment:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
        deid_payment_aggregate:
          type: object
          properties:
            aggregate:
              type: object
              properties:
                count:
                  type: integer
                  example: 15
                sum:
                  type: object
                  properties:
                    amount:
                      type: number
                      format: decimal
                      description: Total payment amount
                      example: 28750
    StaffListResponse:
      type: object
      description: Standard response format for staff endpoints
      properties:
        deid_staff:
          type: array
          items:
            $ref: '#/components/schemas/StaffComplete'
        deid_staff_aggregate:
          $ref: '#/components/schemas/AggregateCount'
    WIPListResponse:
      type: object
      description: Standard response format for WIP endpoints
      properties:
        deid_wip:
          type: array
          items:
            $ref: '#/components/schemas/WIP'
        deid_wip_aggregate:
          $ref: '#/components/schemas/WIPAggregate'
    TransactionType:
      type: string
      enum:
        - Receipt
        - Invoice
        - Payment
        - Credit
        - Adjustment
      description: Available AR transaction types
    PaymentMethod:
      type: string
      enum:
        - CREDIT_CARD
        - DEBIT_CARD
        - ACH
        - BANK_TRANSFER
        - CHECK
        - WIRE
        - PAYPAL
        - APPLE_PAY
        - GOOGLE_PAY
      description: Available payment methods
    PaymentStatus:
      type: string
      enum:
        - PENDING
        - CONFIRMED
        - FAILED
        - CANCELLED
        - REFUNDED
      description: Available payment statuses
    InvoiceStatus:
      type: string
      enum:
        - PENDING
        - POSTED
        - PAID
        - OVERDUE
        - CANCELLED
        - DRAFT
      description: Available invoice statuses
    EngagementStatus:
      type: string
      enum:
        - ACTIVE
        - COMPLETED
        - ON_HOLD
        - EXECUTED
        - CANCELLED
        - PLANNED
      description: Available engagement statuses
    WIPType:
      type: string
      enum:
        - Time
        - Expense
        - Fixed_Fee
        - Disbursement
      description: Available WIP types
    SortOrder:
      type: string
      enum:
        - asc
        - desc
      description: Sort order options
    ContactListResponse:
      type: object
      description: Standard response format for contact endpoints
      properties:
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        total:
          $ref: '#/components/schemas/AggregateCount'
    ProjectListResponse:
      type: object
      description: Standard response format for project endpoints
      properties:
        projects:
          type: array
          items:
            $ref: '#/components/schemas/Project'
        total:
          $ref: '#/components/schemas/AggregateCount'
    StaffUserTaskListResponse:
      type: object
      description: Standard response format for staff user task endpoints
      properties:
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/StaffUserTask'
        total:
          $ref: '#/components/schemas/AggregateCount'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Firebase JWT Bearer token authentication with Hasura integration for
        user-based access.


        **Usage:**

        ```

        Authorization: Bearer <jwt-token>

        ```


        **Token Requirements:**

        - JWT tokens are issued by Firebase Authentication (Google Secure Token
        Service)

        - Tokens contain Hasura role-based permissions and tenant context

        - Standard expiration time: 1 hour (3600 seconds)

        - Supports SAML/Google identity providers

        - Contains both application roles and Hasura-specific claims


        **Token Structure:**

        ```json

        {
          "https://hasura.io/jwt/claims": {
            "x-hasura-allowed-roles": [
              "aiwynsb_SUPER_ADMIN",
              "aiwynsb_API_USER", 
              "aiwynsb_API_ADMIN"
            ],
            "x-hasura-default-role": "aiwynsb_API_ADMIN"
          },
          "staffId": 420,
          "tenant": "aiwynsb",
          "roles": ["SUPER_ADMIN", "aiwynsb_API_ADMIN"],
          "email": "user@aiwyn.ai",
          "authKeyId": 11,
          "iss": "https://securetoken.google.com/an-staging-302521",
          "aud": "an-staging-302521",
          "auth_time": 1758777932,
          "user_id": "ocGkQDCe0MgLudgrjR18h5oKuVE2",
          "sub": "ocGkQDCe0MgLudgrjR18h5oKuVE2",
          "iat": 1758777932,
          "exp": 1758781532,
          "email_verified": true,
          "firebase": {
            "identities": {
              "saml.google": ["user@aiwyn.ai"],
              "email": ["user@aiwyn.ai"]
            },
            "sign_in_provider": "custom",
            "tenant": "aiwynsandbox-firm-o64vu"
          }
        }

        ```


        **Example:**

        ```bash

        curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
        \
             https://api.yourdomain.com/v1/clients
        ```
    SecurityHeaders:
      type: object
      description: |
        Additional security headers that may be required or optional
        depending on the authentication method and tenant configuration.
      properties:
        X-Tenant-ID:
          type: string
          description: >
            Explicit tenant identifier (optional when using JWT tokens that
            contain tenant info)
          example: aiwynsb
        X-Request-ID:
          type: string
          format: uuid
          description: |
            Unique request identifier for tracing and debugging
          example: 550e8400-e29b-41d4-a716-446655440000
        X-Client-Version:
          type: string
          description: |
            Client application version for compatibility checking
          example: 1.2.3
        X-Forwarded-For:
          type: string
          description: |
            Original client IP address (when using proxy/load balancer)
          example: 203.0.113.195
