---
openapi: 3.0.3

info:
  version: 1.0.0
  title: OWS Store API Specifications
  description: Microservice handling stores (AKA DMSs, partners)

servers:
  - url: https://qa-ows-store.theorchard.io
    description: QA environment
  - url: https://ows-store.theorchard.io
    description: Production environment

paths:
  /hello/:
    get:
      summary: Check the health of the application
      description: Health check endpoint to verify the application is running
      operationId: health
      responses:
        '200':
          description: OK - Application is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
              example:
                status: ok

  /stores:
    get:
      summary: Fetch all stores
      description: Retrieve a list of all stores with optional filtering and sorting
      operationId: getStores
      parameters:
        - $ref: '#/components/parameters/OrchardIdentityId'
        - $ref: '#/components/parameters/OrchardProfileId'
        - $ref: '#/components/parameters/OrchardProfileType'
        - name: supports_timed_release
          in: query
          description: Filter by stores that support timed release
          required: false
          schema:
            type: string
            enum: [true, false]
        - name: classification_id
          in: query
          description: Filter by classification ID
          required: false
          schema:
            type: integer
        - name: status
          in: query
          description: Filter by store status (comma-separated for multiple)
          required: false
          schema:
            type: string
            example: "active,onboarding"
        - name: order_by
          in: query
          description: Field to order results by
          required: false
          schema:
            type: string
        - name: order_dir
          in: query
          description: Order direction
          required: false
          schema:
            type: string
            enum: [asc, desc]
      responses:
        '200':
          description: Successfully retrieved stores
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: ok
                  message:
                    type: array
                    items:
                      $ref: '#/components/schemas/Store'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /stores/dataloader:
    post:
      summary: Fetch stores by store IDs
      description: Retrieve stores for the given list of store IDs (dataloader pattern)
      operationId: getStoresDataloader
      parameters:
        - $ref: '#/components/parameters/OrchardIdentityId'
        - $ref: '#/components/parameters/OrchardProfileId'
        - $ref: '#/components/parameters/OrchardProfileType'
        - $ref: '#/components/parameters/ContentType'
      requestBody:
        description: Array of store IDs
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: integer
              example: [1, 2, 3]
      responses:
        '200':
          description: Successfully retrieved stores
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: ok
                  message:
                    type: array
                    items:
                      $ref: '#/components/schemas/Store'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /stores/distribution_types/dataloader:
    post:
      summary: Fetch store distribution types by store IDs
      description: Retrieve distribution types for the given list of store IDs (dataloader pattern)
      operationId: getStoreDistributionTypesDataloader
      parameters:
        - $ref: '#/components/parameters/OrchardIdentityId'
        - $ref: '#/components/parameters/OrchardProfileId'
        - $ref: '#/components/parameters/OrchardProfileType'
        - $ref: '#/components/parameters/ContentType'
      requestBody:
        description: Array of store IDs
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: integer
              example: [1, 2, 3]
      responses:
        '200':
          description: Successfully retrieved distribution types
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: ok
                  message:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        $ref: '#/components/schemas/DistributionType'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /stores/classifications/dataloader:
    post:
      summary: Fetch store classifications by store IDs
      description: Retrieve classifications for the given list of store IDs (dataloader pattern)
      operationId: getStoreClassificationsDataloader
      parameters:
        - $ref: '#/components/parameters/OrchardIdentityId'
        - $ref: '#/components/parameters/OrchardProfileId'
        - $ref: '#/components/parameters/OrchardProfileType'
        - $ref: '#/components/parameters/ContentType'
      requestBody:
        description: Array of store IDs
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: integer
              example: [1, 2, 3]
      responses:
        '200':
          description: Successfully retrieved classifications
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: ok
                  message:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        $ref: '#/components/schemas/Classification'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /substores/dataloader:
    post:
      summary: Fetch substores by store IDs
      description: Retrieve substores for the given list of store IDs (dataloader pattern)
      operationId: getSubstoresDataloader
      parameters:
        - $ref: '#/components/parameters/OrchardIdentityId'
        - $ref: '#/components/parameters/OrchardProfileId'
        - $ref: '#/components/parameters/OrchardProfileType'
        - $ref: '#/components/parameters/ContentType'
      requestBody:
        description: Array of store IDs
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: integer
              example: [1, 2, 3]
      responses:
        '200':
          description: Successfully retrieved substores
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: ok
                  message:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        $ref: '#/components/schemas/Substore'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

components:
  parameters:
    OrchardUserId:
      in: header
      name: Orchard-User-Id
      required: true
      schema:
        type: string
        pattern: '^oa:.+'
      description: Orchard user ID from OA
    ContentType:
      in: header
      name: Content-Type
      required: true
      schema:
        type: string
        pattern: '^application/json'
        default: application/json
    OrchardIdentityId:
      in: header
      name: Orchard-Identity-Id
      required: true
      schema:
        type: string
      description: Orchard identity id
    OrchardProfileId:
      in: header
      name: Orchard-Profile-Id
      required: true
      schema:
        type: integer
      description: Orchard profile id
    OrchardProfileType:
      in: header
      name: Orchard-Profile-Type
      required: true
      schema:
        type: string
      description: Orchard profile type

  schemas:
    Store:
      type: object
      properties:
        id:
          type: integer
          description: Store ID (customer_master_master_id)
          example: 123
        name:
          type: string
          description: Store name
          example: "Example Store"
        supports_timed_release:
          type: boolean
          description: Whether the store supports timed release
          example: true
        status:
          type: string
          description: Store status
          enum: [active, inactive, terminated, reporting only, onboarding, suspended]
          example: active

    DistributionType:
      type: object
      properties:
        id:
          type: integer
          description: Distribution type ID
          example: 1
        name:
          type: string
          description: Distribution type name
          example: "Digital"

    Classification:
      type: object
      properties:
        id:
          type: integer
          description: Classification ID
          example: 1
        classification:
          type: string
          description: Classification name
          example: "Streaming"

    Substore:
      type: object
      properties:
        customer_id:
          type: integer
          description: Substore ID (customer_id)
          example: 456
        customer_master_master_id:
          type: integer
          description: Parent store ID
          example: 123
        territory:
          type: integer
          description: Territory ID
          example: 1
          nullable: true

    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: bad_request
        message:
          type: string
          description: Error message
          example: Invalid request

  responses:
    UnauthorizedError:
      description: Authentication information is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: authorization_error
            message: "You don't have access to this resource!"
    ForbiddenError:
      description: User is forbidden to access this resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: forbidden
            message: "User is forbidden"