# schema: https://spec.openapis.org/oas/v3.1.1.html
openapi: 3.1.1
info:
  version: 1.0.0
  title: ows-abacus-contract

#-------------------------------
# Servers
#-------------------------------
servers:
  - url: "https://prod-ows-abacus-contract.theorchard.io"
    description: Prod
  - url: "https://qa-ows-abacus-contract.theorchard.io"
    description: QA
  - url: "https://uat-ows-abacus-contract.theorchard.io"
    description: UAT

#-------------------------------
# Paths
#-------------------------------
paths:
  /contract/{contract_id}/:
    get:
      description: Retrieves contract details
      operationId: getContract
      parameters:
        - $ref: "#/components/parameters/ContractId"
        - $ref: "#/components/parameters/CorrelationId"
      responses:
        "200":
          $ref: "#/components/responses/Contract"
        "404":
          $ref: "#/components/responses/Http404"

    put:
      description: Update contract details for a specified contract
      operationId: updateContract
      parameters:
        - $ref: "#/components/parameters/ContractId"
        - $ref: "#/components/parameters/CorrelationId"
      requestBody:
        $ref: "#/components/requestBodies/UpdateContract"
      responses:
        "200":
          $ref: "#/components/responses/Contract"
        "404":
          $ref: "#/components/responses/Http404"

  /contract/{contract_id}/contract-lifecycle/:
    get:
      description: Get the contract lifecycle associated to the specified contract
      operationId: getContractLifecycle
      parameters:
        - $ref: "#/components/parameters/ContractId"
      responses:
        "200":
          $ref: "#/components/responses/ContractLifecycle"
        "400":
          $ref: "#/components/responses/Http400"

  /contract/{contract_id}/terminate/:
    put:
      description: Terminate a contract
      operationId: terminateContract
      parameters:
        - $ref: "#/components/parameters/ContractId"
        - $ref: "#/components/parameters/CorrelationId"
      requestBody:
        $ref: "#/components/requestBodies/TerminateContract"
      responses:
        "200":
          $ref: "#/components/responses/Contract"
        "400":
          $ref: "#/components/responses/Http400"

  /contract/{contract_id}/reactivate/:
    put:
      description: Reactivate a contract
      operationId: reactivateContract
      parameters:
        - $ref: "#/components/parameters/ContractId"
        - $ref: "#/components/parameters/CorrelationId"
      responses:
        "200":
          $ref: "#/components/responses/Contract"

  /contracts/:
    post:
      description: Get a list of contracts by contract_id
      operationId: getContracts
      requestBody:
        $ref: "#/components/requestBodies/GetContracts"
      responses:
        "200":
          $ref: "#/components/responses/Contracts"

  /contracts/dataloader/:
    post:
      description: Get a list of contracts by contract_id
      operationId: dataloadContracts
      requestBody:
        $ref: "#/components/requestBodies/GetContracts"
      responses:
        "200":
          $ref: "#/components/responses/DataloadContracts"

  /hello/:
    get:
      description: Check the health of the application.
      operationId: getHealth
      parameters:
        - $ref: "#/components/parameters/CorrelationId"
      responses:
        "200":
          $ref: "#/components/responses/Health"
      tags:
        - Get
        - Health

components:
  #-------------------------------
  # Reusable parameters
  #-------------------------------
  parameters:
    ContractId:
      description: The contract ID
      in: path
      name: contract_id
      required: true
      schema:
        $ref: "#/components/schemas/ContractId"

    CorrelationId:
      description: Correlation ID
      in: header
      name: Correlation-Id
      required: false
      schema:
        type: string

  #-------------------------------
  # Reusable Request Bodies
  #-------------------------------
  requestBodies:
    GetContracts:
      description: List of contract_ids.
      required: true
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/ContractId"

    TerminateContract:
      description: Termination details
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              termination_effective:
                $ref: "#/components/schemas/ContractTerminationEffective"
              termination_notice_received:
                $ref: "#/components/schemas/ContractTerminationNoticeReceived"
            required:
              - termination_effective
          example:
            termination_effective: "2024-08-27"
            termination_notice_received: "2024-08-20"

    UpdateContract:
      description: Update details
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              contract_name:
                $ref: "#/components/schemas/ContractName"
              general_note:
                type: string
                description: General notes related to the contract
              execution_date:
                description: date on which the contract was countersigned
                $ref: "#/components/schemas/Date"
              initial_start_date:
                description: date on which the contract is first activated
                $ref: "#/components/schemas/Date"
              is_excluded_from_accounting_run:
                description: whether a contract should be used during the accounting run calculation(by default all contracts are included)
                type: boolean
              reference_sap_profit_center_id:
                type: integer
                description: ID of contract's SAP-related metadata
              reference_signing_entity_id:
                type: integer
                description: ID of related reference_signing_entity
              sap_created_at:
                description: date contract data was sent to SAP
                $ref: "#/components/schemas/Date"
              summary_note:
                type: string
                description: Summary notes related to the contract
              term_end:
                deprecated: true
                description: contract's term end date
                $ref: "#/components/schemas/Date"
              term_start:
                deprecated: true
                description: contract's term start date
                $ref: "#/components/schemas/Date"
          example:
            contract_name: "Best Contract"
            reference_sap_profit_center_id: 1
            sap_created_at: "2019-06-01"
            summary_note: "Best Contract summary notes"
            general_note: "Best Contract general notes"
            is_excluded_from_accounting_run: 1
            execution_date: "2019-08-08"

  #-------------------------------
  # Reusable Responses
  #-------------------------------
  responses:
    Http400:
      description: Bad data received in payload

    Http404:
      description: 404 NOT FOUND

    Contract:
      description: A JSON object containing Contract data
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Contract"

    ContractLifecycle:
      description: A JSON object containing Contract Lifecycle data
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ContractLifecycle"

    ContractLifecycles:
      description: A JSON array of contract lifecycles
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/ContractLifecycle"

    Contracts:
      description: A JSON array containing Contract data
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/Contract"

    DataloadContracts:
      description: Success
      content:
        application/json:
          schema:
            type: array
            description: "[ {data: AbacusContract | null } ]"
            items:
              description: "{data: AbacusContract | null }"
              type: object
              properties:
                data:
                  $ref: "#/components/schemas/Contract"
                  nullable: true
            required:
              - items

    Health:
      description: A JSON object containing server health
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Health"

  #-------------------------------
  # Reusable Security Schemes
  #-------------------------------
  securitySchemes:
    IdentityId:
      in: header
      name: Orchard-Identity-Id
      type: apiKey

  #-------------------------------
  # Reusable schemas (data models)
  #-------------------------------
  schemas:
    #-------------------------------
    # Properties
    #-------------------------------
    AccountId:
      description: The contract's account ID
      type: integer
      minimum: 0

    ContractId:
      description: Abacus contract ID
      type: integer
      minimum: 0

    ContractLifecycleId:
      description: ID of the contract_lifecycle
      type: number
      minimum: 0

    ContractLifecycleScheduleId:
      description: Foreign key to contract_lifecycle_schedule table
      type: number
      minimum: 0

    ContractLifecycleStatus:
      description: Contract lifecycle status
      type: string
      enum:
        - active
        - in_collection_period
        - inactive
        - init
        - terminated
        - to_be_terminated

    ContractName:
      description: Abacus contract name
      type: string

    ContractType:
      description: The contract type
      type: string
      enum:
        - distribution
        - legacy_distribution
        - neighbouring_rights

    ContractTerminationEffective:
      $ref: "#/components/schemas/Date"

    ContractTerminationNoticeReceived:
      $ref: "#/components/schemas/Date"

    Date:
      description: A datetime string formatted as YYYY-MM-DD
      format: date
      type: string

    DateTime:
      description: A datetime string formatted as YYYY-MM-DDTHH:MM:SS.fz
      format: date-time
      type: string

    #-------------------------------
    # Models
    #-------------------------------
    PartialContract:
      type: object
      properties:
        account_id:
          $ref: "#/components/schemas/AccountId"
        contract_id:
          $ref: "#/components/schemas/ContractId"
        contract_name:
          $ref: "#/components/schemas/ContractName"
        contract_type:
          default: "distribution"
          $ref: "#/components/schemas/ContractType"
        created_at:
          description: date contract was created
          $ref: "#/components/schemas/Date"
        created_by:
          type: string
        execution_date:
          description: date on which the contract was countersigned
          $ref: "#/components/schemas/Date"
        general_note:
          description: General notes related to the contract
          type: string
        initial_start_date:
          description: date on which the contract is first activated
          $ref: "#/components/schemas/Date"
        is_excluded_from_accounting_run:
          description: whether a contract should be used during the accounting run calculation(by default all contracts are included)
          type: boolean
        last_modified:
          description: date contract was last modified
          $ref: "#/components/schemas/Date"
        last_modified_by:
          type: string
        oa_contract_id:
          type: integer
          description: ID of OA contract
        reference_sap_profit_center_id:
          type: integer
          description: ID of SAP-related metadata
        reference_signing_entity_id:
          type: integer
          description: ID of related reference_signing_entity
        sap_created_at:
          description: date contract data was sent to SAP
          $ref: "#/components/schemas/Date"
        summary_note:
          description: Summary notes related to the contract
          type: string
        term_end:
          deprecated: true
          description: The contract's term end date
          $ref: "#/components/schemas/Date"
        term_start:
          deprecated: true
          description: The contract's term start date
          $ref: "#/components/schemas/Date"

    Contract:
      title: Contract Details
      allOf:
        - $ref: "#/components/schemas/PartialContract"
      required:
        - contract_id
        - contract_name
        - contract_type
      example:
        account_id: 12
        contract_id: 10
        contract_name: "Best Contract"
        contract_type: "distribution"
        oa_contract_id: 123
        reference_sap_profit_center_id: 1
        reference_signing_entity_id: 1
        summary_note: "Best Contract summary notes"
        general_note: "Best Contract general notes"
        sap_created_at: "2022-06-01"
        initial_start_date: "2019-06-01"
        execution_date: None
        is_excluded_from_accounting_run: false

    ContractLifecycle:
      title: Contract Lifecycle
      type: object
      properties:
        contract_lifecycle_id:
          $ref: "#/components/schemas/ContractLifecycleId"
        contract_id:
          $ref: "#/components/schemas/ContractId"
        contract_lifecycle_schedule_id:
          $ref: "#/components/schemas/ContractLifecycleScheduleId"
        lifecycle_status:
          $ref: "#/components/schemas/ContractLifecycleStatus"
        lifecycle_term_start:
          description: contract's term start date
          $ref: "#/components/schemas/Date"
        lifecycle_term_end:
          description: contract's term end date
          $ref: "#/components/schemas/Date"
        renewal_effective:
          description: contract's renewal date and it is same as lifecycle_term_end column
          $ref: "#/components/schemas/Date"
        termination_notice_deadline:
          description:
            date indicates how long before the contract ends that a client must inform the business that
            they wish to terminate a contract
          $ref: "#/components/schemas/Date"
        termination_notice_received:
          description: date explicitly set by the user when they choose to terminate a contract
          $ref: "#/components/schemas/Date"
        termination_effective:
          description: date set by the user when they terminate a contract
          $ref: "#/components/schemas/Date"
        collection_start:
          description:
            date field used by NR contracts only and it will always be the day after the
            lifecycle_term_end
          $ref: "#/components/schemas/Date"
        collection_end:
          description:
            date field used by NR contracts only and is determined using the lifecycle_term_end plus the
            collection_start date
          $ref: "#/components/schemas/Date"
      example:
        contract_lifecycle_id: 1
        contract_id: 1
        contract_lifecycle_schedule_id: 1
        lifecycle_status: "active"
        lifecycle_term_start: "2024-07-03"
        lifecycle_term_end: None
        renewal_effective: None
        termination_notice_deadline: None
        termination_notice_received: None
        termination_effective: None
        collection_start: None
        collection_end: None

    Health:
      type: object
      properties:
        status:
          type: string
          enum:
            - ok
      required:
        - status

#-------------------------------
# Global security settings
#-------------------------------
security:
  - IdentityId: []