openapi.yaml

x-todoIDSchema: &x-todoIDSchema
  type: string
  format: uuid
  x-go-type: "todoDomain.TodoID"
  x-go-type-import:
    path: "github.com/danicc097/todo-ddd-example/internal/modules/todo/domain"
    name: "todoDomain"

x-tagIDSchema: &x-tagIDSchema
  type: string
  format: uuid
  x-go-type: "todoDomain.TagID"
  x-go-type-import:
    path: "github.com/danicc097/todo-ddd-example/internal/modules/todo/domain"
    name: "todoDomain"

x-userIDSchema: &x-userIDSchema
  type: string
  format: uuid
  x-go-type: "userDomain.UserID"
  x-go-type-import:
    path: "github.com/danicc097/todo-ddd-example/internal/modules/user/domain"
    name: "userDomain"

x-workspaceIDSchema: &x-workspaceIDSchema
  type: string
  format: uuid
  x-go-type: "workspaceDomain.WorkspaceID"
  x-go-type-import:
    path: "github.com/danicc097/todo-ddd-example/internal/modules/workspace/domain"
    name: "workspaceDomain"

x-todoIDParameter: &x-todoIDParameter
  name: id
  in: path
  required: true
  schema:
    *x-todoIDSchema

x-tagIDParameter: &x-tagIDParameter
  name: id
  in: path
  required: true
  schema:
    *x-tagIDSchema

x-userIDParameter: &x-userIDParameter
  name: id
  in: path
  required: true
  schema:
    *x-userIDSchema

x-workspaceIDParameter: &x-workspaceIDParameter
  name: id
  in: path
  required: true
  schema:
    *x-workspaceIDSchema

openapi: 3.0.3
info:
  title: Todo DDD API
  version: 1.0.0
  description: A Todo api with delusions of grandeur.
servers:
  - url: http://localhost:8099/api/v1
    description: Local development server
  - url: http://127.0.0.1:8090/api/v1
    description: Local swarm server

paths:
  /healthz:
    get:
      summary: Health check
      operationId: healthz
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
                example: ok

  /auth/register:
    post:
      summary: Register a new user with password
      operationId: register
      x-rate-limit:
        limit: 50
        window: "1m"
      tags:
        - auth
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterUserRequestBody'
      responses:
        '201':
          description: User registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdResponse'

  /auth/login:
    post:
      summary: Login with email and password
      operationId: login
      x-rate-limit:
        limit: 10
        window: "1m"
      tags:
        - auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequestBody'
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponseBody'

  /auth/totp/initiate:
    post:
      summary: Initiate TOTP setup for the user
      operationId: initiateTOTP
      tags:
        - auth
      security:
        - bearerAuth: []
      responses:
        '200':
          description: TOTP setup initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitiateTOTPResponseBody'

  /auth/totp/verify:
    post:
      summary: Verify and activate TOTP
      operationId: verifyTOTP
      x-rate-limit:
        limit: 10
        window: "1m"
      tags:
        - auth
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyTOTPRequestBody'
      responses:
        '200':
          description: TOTP verified, returns new JWT with MFA claim
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponseBody'

  /workspaces/{id}/todos:
    get:
      summary: List all todos for a workspace
      operationId: getWorkspaceTodos
      tags:
        - todo
      parameters:
        - *x-workspaceIDParameter
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A list of todos
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Todo'
    post:
      summary: Create a new todo
      operationId: createTodo
      tags:
        - todo
      parameters:
        - *x-workspaceIDParameter
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTodoRequest'
      responses:
        '201':
          description: Todo created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdResponse'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'

  /todos/{id}:
    get:
      summary: Get a todo by ID
      operationId: getTodoByID
      tags:
        - todo
      parameters:
        - *x-todoIDParameter
      responses:
        '200':
          description: Todo found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Todo'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'

  /todos/{id}/complete:
    patch:
      summary: Complete a todo
      operationId: completeTodo
      tags:
        - todo
      parameters:
        - *x-todoIDParameter
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: Todo completed successfully
        '4XX':
          $ref: '#/components/responses/ErrorResponse'

  /todos/{id}/tags:
    post:
      summary: Assign a tag to a todo
      operationId: assignTagToTodo
      tags:
        - todo
      parameters:
        - *x-todoIDParameter
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignTagToTodoRequest'
      responses:
        '204':
          description: Tag assigned
        '4XX':
          $ref: '#/components/responses/ErrorResponse'

  /todos/{id}/focus/start:
    post:
      summary: Start focus session
      operationId: startFocus
      tags:
        - todo
      security:
        - bearerAuth: []
      parameters:
        - *x-todoIDParameter
      responses:
        '204':
          description: Focus started
        '4XX':
          $ref: '#/components/responses/ErrorResponse'

  /todos/{id}/focus/stop:
    post:
      summary: Stop focus session
      operationId: stopFocus
      tags:
        - todo
      security:
        - bearerAuth: []
      parameters:
        - *x-todoIDParameter
      responses:
        '204':
          description: Focus stopped
        '4XX':
          $ref: '#/components/responses/ErrorResponse'

  /schedule/commit:
    post:
      summary: Commit a task to daily schedule
      operationId: commitTask
      tags:
        - schedule
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommitTaskRequest'
      responses:
        '204':
          description: Task committed
        '4XX':
          $ref: '#/components/responses/ErrorResponse'

  /users/{id}:
    get:
      operationId: getUserByID
      security:
        - bearerAuth: []
      parameters:
        - *x-userIDParameter
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

  /users/{id}/workspaces:
    get:
      summary: Get all workspaces for a user
      operationId: getUserWorkspaces
      security:
        - bearerAuth: []
      tags:
        - user
      parameters:
        - *x-userIDParameter
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Workspace'
  /workspaces:
    get:
      summary: List all workspaces
      operationId: listWorkspaces
      security:
        - bearerAuth: []
      tags:
        - workspace
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: List of workspaces
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Workspace'
    post:
      summary: Onboard a new workspace with initial members
      operationId: onboardWorkspace
      tags:
        - workspace
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardWorkspaceRequest'
      responses:
        '201':
          description: Workspace created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /workspaces/{id}:
    delete:
      summary: Delete a workspace
      operationId: deleteWorkspace
      tags:
        - workspace
      security:
        - bearerAuth: []
      parameters:
        - *x-workspaceIDParameter
      responses:
        '204':
          description: Workspace deleted
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /workspaces/{id}/members:
    post:
      summary: Add a member to a workspace
      operationId: addWorkspaceMember
      tags:
        - workspace
      parameters:
        - *x-workspaceIDParameter
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddWorkspaceMemberRequest'
      responses:
        '204':
          description: Member added
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /workspaces/{id}/members/{userId}:
    delete:
      summary: Remove a member from a workspace
      operationId: removeWorkspaceMember
      tags:
        - workspace
      parameters:
        - *x-workspaceIDParameter
        - !!merge <<: *x-userIDParameter
          name: userId
      responses:
        '204':
          description: Member removed
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /workspaces/{id}/tags:
    get:
      summary: Get all tags for a workspace
      operationId: getWorkspaceTags
      tags:
        - workspace
      parameters:
        - *x-workspaceIDParameter
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tag'
    post:
      summary: Create a new tag
      operationId: createTag
      tags:
        - tag
      parameters:
        - *x-workspaceIDParameter
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTagRequest'
      responses:
        '201':
          description: Tag created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdResponse'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  parameters:
    Limit:
      name: limit
      in: query
      description: Maximum number of records to return.
      required: false
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100
    Offset:
      name: offset
      in: query
      description: Number of records to skip.
      required: false
      schema:
        type: integer
        default: 0
        minimum: 0
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      description: >
        Unique key to allow safe retries of non-idempotent requests.
        If a request with the same key is received, the server returns the cached response.
      required: false
      schema:
        type: string
        format: uuid

  schemas:
    IdResponse:
      type: object
      required: [id]
      properties:
        id:
          type: string
          format: uuid

    HTTPValidationError:
      title: HTTPValidationError
      type: object
      required:
        - messages
      properties:
        detail:
          title: Detail
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
        messages:
          title: Messages
          type: array
          items:
            type: string
    ValidationError:
      title: ValidationError
      required:
        - loc
        - msg
        - detail
      type: object
      properties:
        loc:
          title: Location
          type: array
          items:
            type: string
        msg:
          title: Message
          type: string
        detail:
          $ref: '#/components/schemas/ValidationErrorDetail'
        ctx:
          title: Contextual information
          type: object
    ValidationErrorDetail:
      title: ValidationErrorDetail
      description: Details of the error
      type: object
      required:
        - value
      properties:
        value:
          type: string
          description: The actual value that failed validation
    WorkspaceRole:
      type: string
      x-go-type: "workspaceDomain.WorkspaceRole"
      x-go-type-import:
        path: "github.com/danicc097/todo-ddd-example/internal/modules/workspace/domain"
        name: "workspaceDomain"

    OnboardWorkspaceRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: The display name of the workspace.
        description:
          type: string
          description: A brief description of the workspace purpose.
        members:
          description: Initial extra members to add to the workspace.
          x-go-type: "map[uuid.UUID]workspaceDomain.WorkspaceRole"
          x-go-type-import:
            path: "github.com/danicc097/todo-ddd-example/internal/modules/workspace/domain"
            name: "workspaceDomain"

    AddWorkspaceMemberRequest:
      type: object
      required: [userId, role]
      properties:
        userId:
          type: string
          format: uuid
        role:
          $ref: '#/components/schemas/WorkspaceRole'

    Workspace:
      type: object
      required: [id, name, description]
      properties:
        id:
          *x-workspaceIDSchema
        name: { type: string }
        description: { type: string }

    AssignTagToTodoRequest:
      type: object
      required: [tagId]
      properties:
        tagId:
          *x-tagIDSchema

    Todo:
      type: object
      required: [id, title, status, createdAt, workspaceId]
      properties:
        id:
          *x-todoIDSchema
        workspaceId:
          *x-workspaceIDSchema
        title: { type: string }
        status: { $ref: '#/components/schemas/TodoStatus' }
        createdAt: { type: string, format: date-time }
        dueDate: { type: string, format: date-time, nullable: true }
        recurrenceInterval: { $ref: '#/components/schemas/RecurrenceInterval' }
        recurrenceAmount: { type: integer, nullable: true }
        completionLogs:
          type: array
          items:
            $ref: '#/components/schemas/CompletionLog'
        focusSessions:
          type: array
          items:
            $ref: '#/components/schemas/FocusSession'

    CompletionLog:
      type: object
      required: [timestamp, actorId]
      properties:
        timestamp: { type: string, format: date-time }
        actorId:
          *x-userIDSchema

    FocusSession:
      type: object
      required: [id, startTime]
      properties:
        id: { type: string, format: uuid }
        startTime: { type: string, format: date-time }
        endTime: { type: string, format: date-time, nullable: true }

    CreateTodoRequest:
      type: object
      required: [title]
      properties:
        title: { type: string }
        dueDate: { type: string, format: date-time, nullable: true }
        recurrenceInterval: { $ref: '#/components/schemas/RecurrenceInterval' }
        recurrenceAmount: { type: integer, minimum: 1, nullable: true }

    CreateTagRequest:
      type: object
      required: [name]
      properties:
        name: { type: string }

    CommitTaskRequest:
      type: object
      required: [todoId, cost, date]
      properties:
        todoId:
          type: string
          format: uuid
        cost:
          type: integer
          minimum: 1
          maximum: 5
        date:
          type: string
          format: date

    TodoStatus:
      type: string
      enum: [PENDING, COMPLETED, ARCHIVED]

    RecurrenceInterval:
      type: string
      enum: [DAILY, WEEKLY, MONTHLY]
      nullable: true

    LoginRequestBody:
      type: object
      required: [email, password]
      properties:
        email: { type: string, format: email }
        password:
          type: string
          format: password
          x-go-type: "secrecy.Secret[string]"
          x-go-type-import:
            path: "github.com/negrel/secrecy"
            name: "secrecy"

    LoginResponseBody:
      type: object
      required: [accessToken]
      properties:
        accessToken: { type: string }

    InitiateTOTPResponseBody:
      type: object
      required: [provisioningUri]
      properties:
        provisioningUri:
          type: string

    VerifyTOTPRequestBody:
      type: object
      required: [code]
      properties:
        code:
          type: string

    RegisterUserRequestBody:
      type: object
      required: [email, name, password]
      properties:
        email: { type: string, format: email }
        name: { type: string }
        password:
          type: string
          format: password
          minLength: 12
          maxLength: 128
          x-go-type: "secrecy.Secret[string]"
          x-go-type-import:
            path: "github.com/negrel/secrecy"
            name: "secrecy"

    User:
      type: object
      required: [id, email, name]
      properties:
        id:
          *x-userIDSchema
        email: { type: string }
        name: { type: string }

    Tag:
      type: object
      required: [id, name]
      properties:
        id:
          *x-tagIDSchema
        name: { type: string }
  responses:
    ErrorResponse:
      description: General error response
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  trace_id:
                    type: string
                  validation:
                    $ref: '#/components/schemas/HTTPValidationError'