openapi: "3.0.0"
info:
  version: "1.0"
  title: Nextcloud Chores
  license:
    name: AGPL-3.0-only
servers:
  - url: http://localhost:8000/index.php/apps/chores/api/v1.0
security:
  - BasicAuth: []
paths:
  /team:
    get:
      summary: Get team information for the current user
      operationId: getTeam
      tags:
        - team
      responses:
        200:
          description: Team info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Team"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Create a team
      operationId: createTeam
      tags:
        - team
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/Team'}
      responses:
        201:
          description: Team created successfully
        409:
          description: "Conflict: User is already member of a team"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /team/{teamId}:
    parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: integer
          format: teamId
    patch:
      summary: Modify team information
      operationId: modifyTeam
      tags:
        - team
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/Team'}
      responses:
        204:
          description: Team updated successfully
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /account/team:
    get:
      summary: Get team information for the current user
      operationId: getOwnTeam
      tags:
        - user
      responses:
        200:
          description: Team info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Team"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /account/invites:
    get:
      summary: List own pending invitations
      operationId: getOwnInvitations
      tags:
        - user
      responses:
        200:
          description: List of pending invites
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TeamInvite"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /account/invites/accept:
    post:
      summary: Accept a pending invite
      operationId: acceptInvitation
      tags:
        - user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required: [teamId, inviteId]
              properties:
                teamId:
                  type: integer
                  format: teamId
                  example: 1
                inviteId:
                  type: string
                  format: inviteId
                  example: "0yTrbZcQOEHBiAMC"
      responses:
        200:
          description: User successfully joined the team
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /team/{teamId}/invites:
    parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: integer
          format: teamId
    post:
      summary: Invite a user into a team
      operationId: inviteUserToTeam
      tags:
        - team
        - user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required: [userId]
              properties:
                userId:
                  type: string
                  format: userId
      responses:
        204:
          description: User invited successfully or invitation already existed
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /team/{teamId}/chores:
    parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: integer
          format: teamId
    get:
      summary: Get all chores of given team
      operationId: getChoresByTeam
      tags:
        - chores
      responses:
        200:
          description: An array of chores
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Chore"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Add new chore(s)
      operationId: addChoresForTeam
      tags:
        - chores
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required: [chores]
              properties:
                chores:
                  type: array
                  items: {$ref: '#/components/schemas/Chore'}
      responses:
        200:
          description: Saved Successfully
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /team/{teamId}/chores/{choreId}:
    parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: integer
          format: teamId
      - name: choreId
        in: path
        required: true
        schema:
          type: integer
          format: choreId
    patch:
      summary: Modify chore properties
      operationId: modifyChore
      tags:
        - chores
      description: All properties are optional
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/Chore'}
      responses:
        200:
          description: Saved Successfully
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /team/{teamId}/work:
    parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: integer
          format: teamId
      - name: since
        in: query
        schema:
          type: string
          format: date-time
        description: |
          Only return worklog items with a submit_time starting from this time

          Clients can use this to fetch only "new" worklog items by passing the
          `MAX()` of their locally known work items' `submit_time`s
    get:
      summary: Get worklog
      operationId: getWorklog
      tags:
        - worklog
      responses:
        200:
          description: An array of worklog items (may be empty)
          content:
            application/json:
              schema:
                required: [worklog]
                properties:
                  worklog:
                    type: array
                    items:
                      $ref: "#/components/schemas/WorklogItem"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Submit worklog item(s)
      operationId: submitWork
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - work
              properties:
                work:
                  type: array
                  items: {$ref: '#/components/schemas/WorklogSubmissionItem'}
      tags:
        - worklog
      responses:
        200:
          description: Saved Successfully
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
  schemas:
    Chore:
      required:
        - id
        - name
        - points
        - due
        - repeat
      properties:
        id:
          type: integer
          format: choreId
          example: 42
          readOnly: true
        name:
          type: string
          example: "Clean the dishes"
        assignee:
          type: string
          format: userId
          example: alice
        points:
          type: integer
          example: 4
        due:
          type: string
          format: date-time
          description: |
            *Note:* For on-demand tasks, this field holds the "last execution" date
        repeat:
          type: string
          format: repeatSchedule
          example: "w:2:-"
          description: |
            Schedule syntax:
             * "s:0:-" -> single occurence, do not repeat
             * "o:0:-" -> on-demand, repeat indefinetely
             * "d:3:-" -> every three days
             * "w:2:-" -> every two weeks
             * "w:3:1" -> every three weeks, always on Mondays
             * "m:5:22" -> every five months, always on the 22nd
    Team:
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: teamId
          example: 1
          readOnly: true
        name:
          type: string
          example: "Team Awesome"
        owner:
          type: string
          format: userId
          example: bob
        members:
          type: array
          minItems: 1
          uniqueItems: true
          readOnly: true
          items:
            type: string
            format: userId
    TeamInvite:
      required:
        - teamId
        - inviteId
      properties:
        teamId:
          type: integer
          format: teamId
          example: 1
          readOnly: true
        teamName:
          type: string
          example: "Super Team"
          readOnly: true
        userId:
          type: string
          format: userId
          example: "eve"
        inviteId:
          type: string
          example: "0yTrbZcQOEHBiAMC"
          readOnly: true
    WorklogItem:
      required:
        - id
        - work_time
        - chore_id
        - member
      properties:
        id:
          type: string
          format: uuid
          example: 22d1d25c-050e-4076-930e-480a6cd997ec
        work_time:
          type: string
          format: date-time
          description: When the task was done according to the submitting client
        submit_time:
          type: string
          format: date-time
          description: When the worklog item was received by the server
        name:
          type: string
          description: Title of the chore that was completed
          example: "Clean the dishes"
        member:
          type: string
          format: userId
          example: bob
        points:
          type: integer
          example: 4
    WorklogSubmissionItem:
      required:
        - id
        - work_time
        - chore_id
        - member
      properties:
        id:
          type: string
          format: uuid
          example: 22d1d25c-050e-4076-930e-480a6cd997ec
        work_time:
          type: string
          format: date-time
          description: When the task was done according to the submitting client
        chore_id:
          type: integer
          format: choreId
          example: 42
        member:
          type: string
          format: userId
          example: "charlie"
    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string