openapi.yaml

openapi: 3.1.0

info:
  title: Dearly API
  summary: Dearly makes connecting with loved ones easy.
  description: |
    Dearly is a private family-sharing app that bridges generational gaps and makes staying connected easier and more meaningful. The platform allows families to share photos, voice memos, and other media in a secure, invite-only space. With two thoughtfully designed modes, Dearly caters to every generation: a streamlined, user-friendly interface for those less familiar with technology and a dynamic, feature-rich experience for younger users.
  version: 1.0.0

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
    ValidationError:
      type: object
      required:
        - message
        - errors
      properties:
        message:
          type: string
        errors:
          type: array
          items:
            type: object
            required:
              - path
              - message
            properties:
              path:
                type: string
              message:
                type: string
    User:
      type: object
      properties:
        name:
          type: string
          description: Display name of the user.
        username:
          type: string
          description: The username of the user.
        id:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: A unique identifier for the user.
        mode:
          type: string
          enum: ["BASIC", "ADVANCED", null]
          description: The mode for the user (e.g., "BASIC" or "ADVANCED"). Default to "BASIC" if no mode is provided.
        profilePhoto:
          type: string
          nullable: true
          description: A URL to the user's profile photo.
        bio:
          type: string
          nullable: true
          description: A bio for the user's profile.
        birthday:
          type: string
          format: date
          nullable: true
          description: Birthday of the user.
        timezone:
          type: string
          nullable: true
          description: Timezone that user is in for sending nudges.
        postCount:
          type: number
          nullable: true
          description: Number of posts that a user made.
      required:
        - username
        - mode
    ThumbnailResponse:
      type: object
      properties:
        month:
          type: integer
          description: The month of the post.
          example: 1
        year:
          type: integer
          description: The year of the post.
          example: 2025
        data:
          type: array
          items:
            type: object
            properties:
              day:
                type: integer
                description: The day of the month when the post received likes.
                example: 23
              url:
                type: string
                description: URL of the thumbnail image.
                example: "https://example.com/thumbnail.jpg"
          description: A list of thumbnails for the specified month/year.

    Thumbnail:
      type: object
      properties:
        date:
          type: integer
          description: The day of the month the post received likes.
          example: 23
        url:
          type: string
          description: URL to the thumbnail image.
          example: "https://example.com/thumbnail.jpg"
      required:
        - date
        - url

    SearchedUser:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: A unique identifier for the user.
        name:
          type: string
          example: Garrett Ladley
          description: Display name of user.
        username:
          type: string
          example: garrettladley
          description: Username of user.    
        profilePhoto:
          type: string
          description: Profile photo url of user.
          nullable: true
        role:
          type: string
          enum: ["MEMBER", "MANAGER"]
          nullable: true
          description: Defines the role and level of permissions this user in the group has.
        lastNudgedAt:
          type: string
          format: date-time
          example: "2025-01-17T00:00:00Z"
          nullable: true
          description: The date and time when the member was last nudged.                 
      required:
        - id
        - name
        - username
    Group:
      type: object
      properties:
        name:
          type: string
          description: The name of the group.
        description:
          type: string
          description: A description of the group.
          nullable: true
        id:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: A unique identifier for the group.
        managerId:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: A unique identifier of the group manager.
      required:
        - name
    Member:
      type: object
      properties:
        groupId:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: A unique identifier for the group.
        userId:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: A unique identifier for the user in this group.
        nudgeNotificationEnabled:
          type: boolean
          example: true
          description: Return true if user has notification for nudge turned off.
        postNotificationEnabled:
          type: boolean
          example: true
          description: Return true if user has notification for post turned off.
        commentNotificationEnabled:
          type: boolean
          example: true
          description: Return true if user has notification for comment turned off.
        likeNotificationEnabled:
          type: boolean
          example: true
          description: Return true if user has notification for like turned off.
        joinedAt:
          type: string
          format: date-time
          example: "2025-01-17T00:00:00Z"
          description: The date and time when the member was added.
        role:
          type: string
          enum: ["MEMBER", "MANAGER", null]
          description: Defines the role and level of permissions this user in the group has.
    Post:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: A unique identifier for the post.
        groupId:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: A unique identifier for the group.
        userId:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: A unique identifier for the user who makes the post.
        createdAt:
          type: string
          format: date-time
          example: "2025-01-17T00:00:00Z"
          description: The date and time when the post was created.
        caption:
          type: string
          example: "This is a sample caption for the post."
          description: A textual description or caption for the post.
          nullable: true
        name:
          type: string
          description: Display name of user who makes the post.
          nullable: true
        username:
          type: string
          description: Username of user who makes the post.
        likes:
          type: number
          example: 20
          description: Number of likes in a post
        comments:
          type: number
          example: 20
          description: Number of comments in a post
        isLiked:
          type: boolean
          example: true
          description: Return true if user liked the post
        profilePhoto:
          type: string
          nullable: true
          description: Profile photo url of user who made the post
        location:
          type: string
          description: Location of where the post is made
          example: "home"
          nullable: true
        media:
          type: array
          items:
            $ref: "#/components/schemas/Media"
          description: A list of media items attached to the post.

    PostWithURL:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: A unique identifier for the post.
        groupId:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: A unique identifier for the group.
        userId:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: A unique identifier for the user who makes the post.
        createdAt:
          type: string
          format: date-time
          example: "2025-01-17T00:00:00Z"
          description: The date and time when the post was created.
        caption:
          type: string
          example: "This is a sample caption for the post."
          description: A textual description or caption for the post.
          nullable: true
        likes:
          type: number
          example: 20
          description: Number of likes in a post
        comments:
          type: number
          example: 20
          description: Number of comments in a post
        isLiked:
          type: boolean
          example: true
          description: Return true if user liked the post
        profilePhoto:
          type: string
          nullable: true
          description: Profile photo url of user who made the post
        name:
          type: string
          nullable: true
          description: Display name of user who made the post
        username:
          type: string
          description: Username of user who made the post
        location:
          type: string
          description: Location of where the post is made
          example: "home"
          nullable: true
        media:
          type: array
          items:
            $ref: "#/components/schemas/MediaWithURL"
          description: A list of media items attached to the post.

    MediaUpload:
      type: object
      properties:
        type:
          type: string
          example: "PHOTO"
          enum:
            - PHOTO
            - VIDEO
            - AUDIO
          description: The type of the media (e.g., photo, audio, video)
        objectKey:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: The unique object key associated with the media in S3

    Media:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b11
          description: A unique identifier for the media item.
        postId:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: The ID of the post to which the media belongs.
        objectKey:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: The unique object key associated with the media in S3.
        type:
          type: string
          example: "PHOTO"
          enum:
            - PHOTO
            - VIDEO
            - AUDIO
          description: The type of the media (e.g., photo, audio, video).
    Comment:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b11
          description: A unique identifier for the comment item.
        postId:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: The ID of the post to which the comment belongs.
        userId:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: The ID of the user to which the comment belongs.
        voiceMemo:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: The unique object key associated with the audio in S3.
          nullable: true
        content:
          type: string
          minLength: 1
          maxLength: 500
          description: the text being commented
          nullable: true
        createdAt:
          type: string
          format: date-time
          example: "2025-01-17T00:00:00Z"
          description: The date and time when the post was created.
    CommentWithURL:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b11
          description: A unique identifier for the comment item.
        postId:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: The ID of the post to which the comment belongs.
        userId:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: The ID of the user to which the comment belongs.
        voiceMemo:
          type: string
          description: The pre-signed url from AWS S3
          nullable: true
        content:
          type: string
          minLength: 1
          maxLength: 500
          description: The text being commented
          nullable: true
        profilePhoto:
          type: string
          description: Profile photo of user that posted comment
          nullable: true
        username:
          type: string
          description: Username of user that posted comment
          nullable: true
        createdAt:
          type: string
          format: date-time
          example: "2025-01-17T00:00:00Z"
          description: The date and time when the post was created.
    MediaWithURL:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b11
          description: A unique identifier for the media item.
        postId:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: The ID of the post to which the media belongs.
        url:
          type: string
          format: uuid
          description: The pre-signed URL from AWS S3
        type:
          type: string
          example: "PHOTO"
          enum:
            - PHOTO
            - VIDEO
            - AUDIO
          description: The type of the media (e.g., photo, audio, video).
    Notification:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: The ID of the specific notification delivered to a user.
        actorId:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: The ID of the user that performed an action onto the current user.
        receiverId:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: The ID of the user that receives the notification.
        referenceType:
          type: string
          example: "POST"
          enum: ["POST", "COMMENT", "LIKE", "NUDGE", "LIKE-COMMENT"]
          description: The type of notification that occurred, either a new post or an interaction with user media.
        postId:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: The ID of the post that the notification is associated with.
          nullable: true
        commentId:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd4-799178870b10
          description: The ID of the comment that the notification is associated with.
          nullable: true
        likeId:
          type: string
          format: uuid
          example: 5e91507e-5630-4efd-9fd-9fd4-799178870b10
          description: The ID of the like that the notification is associated with.
          nullable: true
        title:
          type: string
          maxLength: 100
          description: The header text of a notification.
          example: "New post from Mom"
        description:
          type: string
          maxLength: 300
          description: The body text of a notification.
          example: "Mom liked your post."
        mediaURL:
          type: string
          description: The URL of the media associated with the notification.
        profilePhoto:
          type: string
          description: The URL of user's profile photo associated with the notification.
          nullable: true
        createdAt:
          type: string
          format: date-time
          example: "2025-01-17T00:00:00Z"
          description: The date and time when the notification was created.
      required:
        - actorId
        - receiverId
        - referenceType
        - title
        - createdAt
        - mediaURL
        - postId
      oneOf:
        - required:
            - postId
        - required:
            - commentId
        - required:
            - likeId
    Schedule:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID of nudge schedule
          example: "3a6e07ab-9b7b-4e0d-b10f-c7fe945f8476"
        groupId:
          type: string
          format: uuid
          description: ID of group
          example: "d0c41d3f-dc80-4a62-a3b2-6e057c0f9981"
        frequency:
          type: string
          description: Frequency of nudge
          enum:
            - DAILY
            - WEEKLY
            - BIWEEKLY
            - MONTHLY
            - YEARLY
        daysOfWeek:
          type: array
          nullable: true
          description: Days of week to send nudge (use with WEEKLY/BIWEEKLY)
          items:
            type: string
            enum:
              - MON
              - TUE
              - WED
              - THU
              - FRI
              - SAT
              - SUN
        day:
          type: integer
          description: Day to send nudge (use with MONTHLY/YEARLY)
          minimum: 1
          maximum: 31
          nullable: true
        month:
          type: integer
          description: Month to send nudge (use with YEARLY)
          minimum: 1
          maximum: 12
          nullable: true
        nudgeAt:
          type: string
          format: date-time
          description: Time with timezone to send nudge
          example: "2025-02-16T08:30:00+00:00"
        isActive:
          type: boolean
          default: true
          description: Status of nudge (active or inactive)
        createdAt:
          type: string
          format: date-time
          description: Time when nudge schedule is initialized
          example: "2025-02-16T08:30:00Z"
        updatedAt:
          type: string
          format: date-time
          description: Time when nudge schedule is updated
          example: "2025-02-16T08:30:00Z"
      required:
        - frequency
        - nudgeAt

    WaveForm:
     type: object
     properties:
        length:
          type: integer
          description: length of the audio message
        data:
          type: array
          items:
            type: integer
            description: the db level at time (index * 500 ms)
          description: The db levels of the given media 

paths:
  /healthcheck:
    get:
      tags:
        - Healthcheck
      summary: Healthcheck endpoint
      description: Pings the server to check the health of the current server
      responses:
        200:
          description: Success!
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    enum:
                      - OK

  /api/v1/users:
    post:
      tags:
        - User Endpoints
      summary: Creates a user
      description: Creates a user from the specified body (with ID being the decoded ID from JWT).
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: Display name of the user.
                username:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: The username of the user.
                mode:
                  type: string
                  enum: ["BASIC", "ADVANCED", null]
                  description: The mode for the user (e.g., "BASIC" or "ADVANCED").
                profilePhoto:
                  type: string
                  nullable: true
                  description: A URL to the user's profile photo.
              required:
                - username
              additionalProperties: true
      responses:
        201:
          description: Successfully created a user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Same JWT creates multiple users or username already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/users/{id}:
    get:
      tags:
        - User Endpoints
      summary: Gets a user
      description: Gets the user by their UUID.
      parameters:
        - name: id
          in: path
          description: ID of the user to get
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      responses:
        200:
          description: Successfully retrieved a User
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/users/me:
    patch:
      tags:
        - User Endpoints
      summary: Updates a user
      description: Updates the user profile for the currently authenticated user (identified by the decoded ID from JWT).
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  description: Display name of the user.
                username:
                  type: string
                  minLength: 1
                  description: The username of the user.
                mode:
                  type: string
                  enum: ["BASIC", "ADVANCED", null]
                  description: The mode for the user (e.g., "BASIC" or "ADVANCED").
                profilePhoto:
                  type: string
                  nullable: true
                  description: A URL to the user's profile photo.
                notificationsEnabled:
                  type: boolean
                  description: True when user wants to receive notifications.
              additionalProperties: true
      responses:
        200:
          description: Successfully updated the user profile
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      tags:
        - User Endpoints
      summary: Deletes a user
      description: Deletes the user account for the currently authenticated user (identified by the decoded ID from JWT).
      security:
        - BearerAuth: []
      responses:
        200:
          description: Successfully delete user
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Successfully delete user"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/users/groups:
    get:
      tags:
        - User Endpoints
      summary: Gets all groups for user
      description: Gets all groups user is member of.
      security:
        - BearerAuth: []
      parameters:
        - name: limit
          in: query
          description: The maximum number of groups to return.
          required: false
          schema:
            type: integer
            default: 10
        - name: page
          in: query
          description: The page number for pagination.
          required: false
          schema:
            type: integer
            default: 1
      responses:
        200:
          description: Successfully retrieve groups user is part of
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Group"
        400:
          description: Malformed query params
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/users/devices:
    post:
      tags:
        - User Endpoints
      summary: Registers user's device token
      description: Registers an Expo Device Token for the currently authenticated user to receive notifications.
      security:
        - BearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                expoToken:
                  type: string
                  description: The Expo Device Token of the user.
              required:
                - expoToken
      responses:
        200:
          description: Successfully registered the device token
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                description: Array of user's device tokens
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      tags:
        - User Endpoints
      summary: Removes user's device token
      description: Removes a registered Expo Device Token for the currently authenticated user to not receive notifications.
      security:
        - BearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                expoToken:
                  type: string
                  description: The Expo Device Token of the user.
              required:
                - expoToken
      responses:
        200:
          description: Successfully removed the device token
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                description: Array of user's remaining device tokens
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/v1/users/notifications:
    get:
      tags:
        - User Endpoints
      summary: Gets a user's notifications
      description: Gets any pending notifications for the current user, along with any associated media depending on the notification type.
      security:
        - BearerAuth: []
      parameters:
        - name: limit
          in: query
          description: The maximum number of notifications to return.
          required: false
          schema:
            type: integer
            default: 5
            example: 5
        - name: page
          in: query
          description: The page number for pagination.
          required: false
          schema:
            type: integer
            default: 1
            example: 1
      responses:
        200:
          description: Successfully retrieved notifications
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Notification"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/v1/groups:
    post:
      tags:
        - Group Endpoints
      summary: Creates a group
      description: Creates a group, a specific circle of family members or friends that are connected within the app.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLengthh: 100
                  description: The name of the group.
                description:
                  type: string
                  maxLength: 500
                  description: A description of the group.
              required:
                - name
      responses:
        201:
          description: Successfully created a group
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    description: The name of the group.
                  description:
                    type: string
                    description: A description of the group.
                    nullable: true
                  id:
                    type: string
                    format: uuid
                    example: 5e91507e-5630-4efd-9fd4-799178870b10
                    description: A unique identifier for the group.
                  managerId:
                    type: string
                    format: uuid
                    example: 5e91507e-5630-4efd-9fd4-799178870b10
                    description: A unique identifier of the group manager.
                required:
                  - name
                  - id
                  - managerId
                  - description
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/groups/{id}:
    get:
      tags:
        - Group Endpoints
      summary: Gets the information of a group
      description: Gets a group's details.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          description: ID of the group to delete
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      responses:
        200:
          description: Succesfully returned a group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      tags:
        - Group Endpoints
      summary: Updates a group
      description: Updates a group, based on what is provided in the request body.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          description: ID of the group to update
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: The name of the group.
                description:
                  type: string
                  maxLength: 500
                  description: A description of the group.
      responses:
        201:
          description: Succesfully deleted a group
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    description: The name of the group.
                  description:
                    type: string
                    description: A description of the group.
                    nullable: true
                  id:
                    type: string
                    format: uuid
                    example: 5e91507e-5630-4efd-9fd4-799178870b10
                    description: A unique identifier for the group.
                  managerId:
                    type: string
                    format: uuid
                    example: 5e91507e-5630-4efd-9fd4-799178870b10
                    description: A unique identifier of the group manager.
                required:
                  - name
                  - id
                  - managerId
                  - description
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    delete:
      tags:
        - Group Endpoints
      summary: Deletes a group
      description: Deletes a group, a specific circle of family members or friends that are connected within the app.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          description: ID of the group to delete
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      responses:
        201:
          description: Successfully delete a group
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Successfully delete post"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/groups/{groupId}/invites:
    get:
      tags:
        - Invite Endpoints
      summary: Gets an invite token
      description: Creates a token that can be used for deeplinking on the client side.
      security:
        - BearerAuth: []
      parameters:
        - name: groupId
          in: path
          description: ID of the group
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      responses:
        200:
          description: Successfully created the unique access token
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                required:
                  - token
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/groups/{token}/verify:
    put:
      tags:
        - Invite Endpoints
      summary: Verifies invite token and adds member
      description: Adds the user with the valid token into the group.
      security:
        - BearerAuth: []
      parameters:
        - name: token
          in: path
          description: token to be invited to the group
          required: true
          schema:
            type: string
      responses:
        200:
          description: Successfully added to group
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Successfully added to group"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/groups/{id}/members/info:
    get:
      tags:
        - Member Endpoints
      summary: Get member info of the group
      description: Get member information if user is member of the group
      parameters:
        - name: id
          in: path
          description: ID of the group.
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      security:
        - BearerAuth: []
      responses:
        200:
          description: Successfully get member's info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Member"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Group not found or user is not member of group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/groups/{id}/members/{userId}:
    post:
      tags:
        - Member Endpoints
      summary: Adds a member to a group
      description: Adds the member to a group.
      parameters:
        - name: id
          in: path
          description: ID of the group.
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
        - name: userId
          in: path
          description: ID of the member to be added.
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      security:
        - BearerAuth: []
      responses:
        201:
          description: Successfully added member to group.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Member"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: User or group not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      tags:
        - Member Endpoints
      summary: Deletes member from group
      description: Deletes member from group.
      parameters:
        - name: id
          in: path
          description: ID of the group.
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
        - name: userId
          in: path
          description: ID of the member to be removed.
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      security:
        - BearerAuth: []
      responses:
        200:
          description: Successfully removed a member from a group
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Successfully removed a member from this group"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: Forbidden if the member being removed is not the group manager or the member themself.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/groups/{id}/members:
    get:
      tags:
        - Member Endpoints
      summary: Gets members of this group
      description: Gets all the members in this group.
      parameters:
        - name: id
          in: path
          description: ID of the group
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
        - name: limit
          in: query
          description: The maximum number of members to return per request.
          required: false
          schema:
            type: integer
            default: 10
        - name: offset
          in: query
          description: The number of members to skip before starting to collect the result set.
          required: false
          schema:
            type: integer
            default: 0
      security:
        - BearerAuth: []
      responses:
        200:
          description: Successfully retrieved members
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SearchedUser"              
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: Forbidden since user is not member of the group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Group not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/groups/{id}/members/notifications:
    patch:
      tags:
        - Member Endpoints
      summary: Toggle member's notification for a group
      description: Turn on or off notification for a group
      parameters:
        - name: id
          in: path
          description: ID of the group
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                nudgeNotificationEnabled:
                  type: boolean
                  example: true
                  description: Return true if user has notification for nudge turned off.
                postNotificationEnabled:
                  type: boolean
                  example: true
                  description: Return true if user has notification for post turned off.
                commentNotificationEnabled:
                  type: boolean
                  example: true
                  description: Return true if user has notification for comment turned off.
                likeNotificationEnabled:
                  type: boolean
                  example: true
                  description: Return true if user has notification for like turned off.
              additionalProperties: true
      responses:
        200:
          description: Successfully update group notification configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Member"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: Forbidden since user is not member of the group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Group not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/groups/{id}/members/{userId}/posts:
    get:
      tags:
        - Member Endpoints
      summary: Gets all posts for user in a group
      description: Gets all posts that a user posted in a group.
      security:
        - BearerAuth: []
      parameters:
        - name: limit
          in: query
          description: The maximum number of posts to return.
          required: false
          schema:
            type: integer
            default: 10
        - name: page
          in: query
          description: The page number for pagination.
          required: false
          schema:
            type: integer
            default: 1
        - name: id
          in: path
          description: ID of the group
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
        - name: userId
          in: path
          description: ID of the user to get posts
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      responses:
        200:
          description: Successfully retrieve posts user posted in a specific group
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/PostWithURL"
        400:
          description: Malformed query params
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/v1/groups/{id}/posts:
    post:
      tags:
        - Post Endpoints
      summary: Creates a post
      description: Creates a post from the specified body.
      parameters:
        - name: id
          in: path
          description: ID of the group a post is made in
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                caption:
                  type: string
                  minLength: 1
                  maxLength: 500
                  description: Caption of the post.
                media:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - VIDEO
                          - PHOTO
                        description: The type of media (either VIDEO or PHOTO).
                      objectKey:
                        type: string
                        description: The object key of the media item to retrieve signed URL from S3.
                    required:
                      - type
                      - objectKey
                  description: A list of media items, each with a type and object key.
              required:
                - media
              additionalProperties: true
      responses:
        201:
          description: Successfully created a post
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Post"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Group not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/posts/{id}:
    get:
      tags:
        - Post Endpoints
      summary: Gets a post
      description: Gets a post's details.
      parameters:
        - name: id
          in: path
          description: ID of the post
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      security:
        - BearerAuth: []
      responses:
        200:
          description: Successfully retrieved a post
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostWithURL"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Post not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      tags:
        - Post Endpoints
      summary: Updates a post
      description: Updates a post from the specified body.
      parameters:
        - name: id
          in: path
          description: ID of the post
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                caption:
                  type: string
                  minLength: 1
                  maxLength: 500
                  description: Caption of the post.
                media:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - VIDEO
                          - PHOTO
                        description: The type of media (either VIDEO or PHOTO).
                      objectKey:
                        type: string
                        description: The object key of the media item.
                    required:
                      - type
                      - objectKey
                  description: A list of media items, each with a type and object key to retrieve signed url from S3.
              additionalProperties: true
      responses:
        200:
          description: Successfully updated a post
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Post"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: Forbidden since user is not a member of a group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Post not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      tags:
        - Post Endpoints
      summary: Deletes a post
      description: Deletes a post.
      parameters:
        - name: id
          in: path
          description: ID of the post
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      security:
        - BearerAuth: []
      responses:
        200:
          description: Successfully delete post
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Successfully delete post"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: Forbidden since user is not creator of post
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/comments/{id}/likes:
    patch:
      tags:
        - Comment Endpoints
      summary: Toggles like on a comment
      description: Likes if user has not liked the comment, unlikes otherwise
      parameters:
        - name: id
          in: path
          description: ID of the comment
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      security:
        - BearerAuth: []
      responses:
        200:
          description: Successfully toggle like of the comment
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Successfully like comment"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: Forbidden since user is not a member of a group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Post not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/posts/{id}/likes:
    patch:
      tags:
        - Like Endpoints
      summary: Toggles like on a post
      description: Likes if user has not liked the post, unlikes otherwise
      parameters:
        - name: id
          in: path
          description: ID of the post
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      security:
        - BearerAuth: []
      responses:
        200:
          description: Successfully toggle like of the post
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Successfully like post"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: Forbidden since user is not a member of a group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Post not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    get:
      tags:
        - Like Endpoints
      summary: Gets all users who like the post
      description: Retrieves list of users who like the post
      parameters:
        - name: id
          in: path
          description: ID of the post
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
        - name: limit
          in: query
          description: The maximum number of groups to return.
          required: false
          schema:
            type: integer
            default: 10
        - name: page
          in: query
          description: The page number for pagination.
          required: false
          schema:
            type: integer
            default: 1
      security:
        - BearerAuth: []
      responses:
        200:
          description: Successfully retrieve users who like the post
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SearchedUser"
        400:
          description: Malformed ID and query params
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: Forbidden since user is not member of the group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Post not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/groups/{id}/feed:
    get:
      tags:
        - Group Endpoints
      summary: Retrieves post feed of a group
      description: Get all the posts from a group, can be filtered by date.
      parameters:
        - name: date
          in: query
          description: The date to filter posts by in YYYY-MM-DD format. If this query param is not provided, it will retrieve all posts in chronological order.
          required: false
          schema:
            type: string
            format: date
        - name: id
          in: path
          description: ID of the group a post is made in
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
        - name: limit
          in: query
          description: The maximum number of groups to return.
          required: false
          schema:
            type: integer
            default: 10
        - name: page
          in: query
          description: The page number for pagination.
          required: false
          schema:
            type: integer
            default: 1
      security:
        - BearerAuth: []
      responses:
        200:
          description: Successfully retrieve post feed
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Post"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: User not member of group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Group not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/groups/{id}/nudges/manual:
    post:
      tags:
        - Nudge Endpoints
      summary: Manually nudge a user
      description: Manager can select at least one member in the group to nudge. Will not nudge if users do not have notifications turned on for groups or for devices.
      parameters:
        - name: id
          in: path
          description: ID of the group to nudge members
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                users:
                  type: array
                  items:
                    type: string
                    format: uuid
                    example: 5e91507e-5630-4efd-9fd4-799178870b10
                  description: User IDs to be nudged
              required:
                - users
              additionalProperties: true

      responses:
        200:
          description: Successfully nudge members
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Successfully nudge selected users"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: User not manager of the group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Group not found or user not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        429:
          description: Cannot nudge during cooldown period to prevent spamming
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/groups/{id}/nudges/auto:
    put:
      tags:
        - Nudge Endpoints
      summary: Upsert nudge schedule for group
      description: Insert or update nudge schedule for a group
      parameters:
        - name: id
          in: path
          description: ID of the group to nudge members
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              frequency:
                type: string
                description: Frequency of nudge
                enum:
                  - DAILY
                  - WEEKLY
                  - MONTHLY
              daysOfWeek:
                type: array
                description: Days of week to send nudge (use with WEEKLY/BIWEEKLY)
                items:
                  type: string
                  enum:
                    - MON
                    - TUE
                    - WED
                    - THU
                    - FRI
                    - SAT
                    - SUN
              day:
                type: integer
                description: Day to send nudge (use with MONTHLY/YEARLY)
                minimum: 1
                maximum: 31
              month:
                type: integer
                description: Month to send nudge (use with YEARLY)
                minimum: 1
                maximum: 12
              nudgeAt:
                type: string
                format: date-time
                description: Time with timezone to send nudge
                example: "2025-02-16T08:30:00+00:00"
      responses:
        200:
          description: Successfully get nudge schedule of group
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Schedule"
                  - type: object
                    properties:
                      message:
                        type: string
                        example: "Group did not have schedule configured"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: User not manager of the group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Group not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    get:
      tags:
        - Nudge Endpoints
      summary: Get group nudge schedule configuration
      description: Retrieve the nudge schedule of a group
      parameters:
        - name: id
          in: path
          description: ID of the group to nudge members
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      security:
        - BearerAuth: []
      responses:
        200:
          description: Successfully get nudge schedule of group
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Schedule"
                  - type: object
                    properties:
                      message:
                        type: string
                        example: "Group did not have schedule configured"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: User not manager of the group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Group not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/v1/groups/{id}/nudges/auto/off:
    put:
      tags:
        - Nudge Endpoints
      summary: Turn nudge to inactive
      description: Deactivate nudge schedule for a group to stop sending nudges
      parameters:
        - name: id
          in: path
          description: ID of the group to nudge members
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      security:
        - BearerAuth: []
      responses:
        200:
          description: Successfully deactivate and turn off nudge
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Schedule"
                  - type: object
                    properties:
                      message:
                        type: string
                        example: "Nudge schedule not configured for deactivation"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: User not manager of the group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Group not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/groups/{id}/calendar:
    get:
      tags:
        - Group Endpoints
      summary: Retrieves calendar view data
      description: Retrieve the thumbnail of media from posts that received likes on specific days, organizing them by month.
      parameters:
        - name: pivot
          in: query
          description: The month and year to retrieve from
          required: false
          schema:
            type: string
            format: date
            default: "{{current_date}}"
        - name: range
          in: query
          description: The number of months to retrieve back from the pivot
          required: false
          schema:
            type: integer
            default: 1
        - name: direction
          in: query
          description: The direction to fetch months relative to the pivot
          required: false
          schema:
            type: string
            enum: [before, after, both]
            default: before
        - name: tmzOffset
          in: query
          description: The number of minutes between UTC and the timezone of the device.
          required: false
          schema:
            type: integer
            default: 240
        - name: tmz
          in: query
          description: Timezone of device.
          required: false
          schema:
            type: string
            default: America/New_York
        - name: id
          in: path
          description: ID of the group a post is made in
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      security:
        - BearerAuth: []
      responses:
        200:
          description: Successfully retrieve calendar info
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ThumbnailResponse"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: User not member of group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Group not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/groups/{id}/media:
    post:
      tags:
        - Media Endpoint
      summary: Upload group-related media to S3 bucket
      description: Upload group-related media to S3 bucket before making a post
      parameters:
        - name: id
          in: path
          description: ID of the group a post is made in
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                media:
                  type: string
                  format: binary
                  description: The file to upload
              required:
                - media
      responses:
        201:
          description: Successfully retrieve object key and type
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/MediaUpload"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: User not member of group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Group not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/posts/{id}/comments:
    get:
      tags:
        - Comment Endpoints
      summary: Get all comments under a post (paginated)
      description: get all comments under a post including fetching the audio from s3 bucket
      parameters:
        - name: id
          in: path
          description: ID of the post the comments are under
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
        - name: limit
          in: query
          description: The maximum number of groups to return.
          required: false
          schema:
            type: integer
            default: 10
        - name: page
          in: query
          description: The page number for pagination.
          required: false
          schema:
            type: integer
            default: 1
      security:
        - BearerAuth: []
      responses:
        200:
          description: Successfully retrieve comments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/CommentWithURL"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: Forbidden since user not member of group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Post not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    post:
      tags:
        - Comment Endpoints
      summary: Creates a comment
      description: Creates a comment from the specified body and associates it with a specific post
      parameters:
        - name: id
          in: path
          description: ID of the post the comment is under
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  format: uuid
                voiceMemo:
                  type: string
                  format: uuid
                createdAt:
                  type: string
                  format: date-time
                  example: "2025-01-17T00:00:00Z"
                  description: The date and time when the post was created.
      responses:
        201:
          description: successfully created a comment
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Comment"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: Forbidden since user not Member of Group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Post not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/comments/{id}:
    delete:
      tags:
        - Comment Endpoints
      summary: Deletes a comment
      description: Deletes a comment and ensures the comment can be deleted.
      parameters:
        - name: id
          in: path
          description: ID of the comment.
          required: true
          schema:
            type: string
            format: uuid
            example: 5e91507e-5630-4efd-9fd4-799178870b10
      security:
        - BearerAuth: []
      responses:
        200:
          description: Successfully deleted a comment
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Successfully deleted comment"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        403:
          description: Forbidden since user is not creator of comment
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/users/media:
    post:
      tags:
        - Media Endpoint
      summary: Upload user-related media to S3 bucket
      description: Allow users to upload their media to S3 bucket (e.g., profile photo)
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                media:
                  type: string
                  format: binary
                  description: The file to upload
              required:
                - media
      responses:
        201:
          description: Successfully retrieve object key and type
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MediaUpload"
        400:
          description: Malformed request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/ValidationError"
        401:
          description: Unauthorized due to invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/media/processing:
    get:
        tags:
          - Media Endpoint
        summary: Returns an array of db levels to use in pre-processing
        description: Allow users to get the db levels from an audio message
        security:
          - BearerAuth: []
        parameters:
          - name: url
            in: query
            description: The url to process from
            required: true
            schema:
              type: string
              example: "https://s3.com"
        responses:
          200:
            description: Successfully retrieve object key and type
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/WaveForm"
          400:
            description: Malformed request
            content:
              application/json:
                schema:
                  oneOf:
                    - $ref: "#/components/schemas/Error"
                    - $ref: "#/components/schemas/ValidationError"
          401:
            description: Unauthorized due to invalid JWT
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/Error"
          500:
            description: Internal server error
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/Error"