swagger.yaml

openapi: 3.0.0
info:
  title: Zendvo Auth API
  version: 1.0.0
  description: API for user registration and authentication

paths:
  /api/auth/register:
    post:
      summary: Register a new user
      description: Creates a new user record with "unverified" status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                  example: user@example.com
                password:
                  type: string
                  format: password
                  minLength: 8
                  example: "StrongP@ss123"
                name:
                  type: string
                  example: "John Doe"
      responses:
        "201":
          description: User created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      userId:
                        type: string
                        format: uuid
                      email:
                        type: string
        "400":
          description: Validation error (invalid email, weak password, missing fields)
        "409":
          description: Email already registered
        "413":
          description: Request body too large
        "429":
          description: Too many registration attempts
        "500":
          description: Internal server error
  /api/auth/forgot-password:
    post:
      summary: Request a password reset
      description: Sends a password reset email if the user exists.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  example: user@example.com
      responses:
        "200":
          description: Success response (always returned for security)
        "400":
          description: Invalid email format
        "429":
          description: Too many requests
        "500":
          description: Internal server error

  /api/auth/reset-password:
    post:
      summary: Reset user password
      description: Resets the password using a valid reset token.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - token
                - password
              properties:
                token:
                  type: string
                  format: uuid
                  example: "550e8400-e29b-41d4-a716-446655440000"
                password:
                  type: string
                  format: password
                  minLength: 8
                  example: "NewStrongP@ss123"
      responses:
        "200":
          description: Password reset successfully
        "400":
          description: Invalid token or weak password
        "500":
          description: Internal server error
  /api/auth/login:
    post:
      summary: User login
      description: Returns access and refresh tokens for valid credentials.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                  example: user@example.com
                password:
                  type: string
                  format: password
                  example: "Password123!"
      responses:
        "200":
          description: Login successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      access_token:
                        type: string
                      refresh_token:
                        type: string
        "401":
          description: Invalid email or password
        "429":
          description: Too many failed attempts from the same IP
        "500":
          description: Internal server error

  /api/auth/refresh:
    post:
      summary: Refresh access token
      description: Returns a new access token using a valid refresh token.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - refreshToken
              properties:
                refreshToken:
                  type: string
      responses:
        "200":
          description: Tokens refreshed
        "401":
          description: Invalid or expired refresh token

  /api/auth/logout:
    post:
      summary: User logout
      description: Invalidates the provided refresh token.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - refreshToken
              properties:
                refreshToken:
                  type: string
      responses:
        "200":
          description: Logged out successfully
        "400":
          description: Missing refresh token
        "401":
          description: Unauthorized

  /api/auth/resend-otp:
    post:
      summary: Resend email verification OTP
      description: Resends a verification code to the authenticated user with a 60 second cooldown.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: OTP resent successfully or already verified
        "401":
          description: Unauthorized
        "404":
          description: User not found
        "429":
          description: Rate limit exceeded
        "500":
          description: Internal server error

  /api/auth/me:
    get:
      summary: Get current user
      description: Returns the authenticated user's profile and verification status.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: User returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  user:
                    type: object
                    properties:
                      id:
                        type: string
                      email:
                        type: string
                        format: email
                      name:
                        type: string
                        nullable: true
                      role:
                        type: string
                      status:
                        type: string
                      createdAt:
                        type: string
                        format: date-time
                      lastLogin:
                        type: string
                        format: date-time
                        nullable: true
                      email_verified:
                        type: boolean
        "401":
          description: Unauthorized
        "404":
          description: User not found
        "500":
          description: Internal server error

  /api/gifts/public:
    post:
      summary: Create a public (anonymous) gift
      description: >
        Allows an unauthenticated sender to create a gift for a registered recipient.
        No authentication is required. Rate limited to 10 requests per 60 seconds per IP.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - recipientId
                - amount
                - senderName
                - senderEmail
              properties:
                recipientId:
                  type: string
                  format: uuid
                  description: ID of the registered recipient user
                  example: "550e8400-e29b-41d4-a716-446655440000"
                amount:
                  type: number
                  description: Gift amount. Must be positive and no greater than 10,000.
                  minimum: 0.01
                  maximum: 10000
                  example: 5000
                senderName:
                  type: string
                  description: Display name of the sender
                  example: "Jane Doe"
                senderEmail:
                  type: string
                  format: email
                  description: Email address of the sender
                  example: "jane@example.com"
                currency:
                  type: string
                  description: Currency code (default NGN)
                  enum:
                    - NGN
                    - USD
                  default: NGN
                  example: "NGN"
                unlockDatetime:
                  type: string
                  format: date-time
                  description: >
                    Optional scheduled delivery datetime in ISO 8601 format with timezone offset.
                    Must be a future date. Example: "2026-04-01T10:00:00+01:00"
                  example: "2026-04-01T10:00:00+01:00"
                hideAmount:
                  type: boolean
                  description: Whether to hide the gift amount from the recipient
                  default: false
                  example: false
                message:
                  type: string
                  description: Optional personal message (max 500 characters)
                  maxLength: 500
                  example: "Happy birthday! Hope this brings a smile 🎉"
                senderAvatar:
                  type: string
                  format: uri
                  description: Optional URL for the sender's avatar image
                  example: "https://example.com/avatar.png"
      responses:
        "201":
          description: Gift created successfully and pending review
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      giftId:
                        type: string
                        format: uuid
                        description: Unique identifier for the created gift
                        example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                      status:
                        type: string
                        description: Initial status of the gift
                        example: "pending_review"
                      slug:
                        type: string
                        description: URL-friendly slug for the gift
                        example: "generous-sunrise-42"
                      shortCode:
                        type: string
                        description: Short alphanumeric code for sharing the gift link
                        example: "XK3T9P"
        "400":
          description: Missing required fields or unsupported currency
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: "recipientId, amount, senderName, and senderEmail are required"
        "404":
          description: Recipient not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: "Recipient not found"
        "409":
          description: Duplicate gift submitted within the last 5 minutes
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: "A similar gift was recently submitted. Please wait before trying again."
        "422":
          description: Validation error (invalid amount, email, message length, or datetime)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: "Amount must be a positive number not exceeding 10,000"
        "429":
          description: Rate limit exceeded (10 requests per 60 seconds per IP)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: "Too many requests. Please try again later."
        "500":
          description: Internal server error

  /api/gifts:
    get:
      summary: Get user gifts
      description: Returns a list of gifts for the authenticated user.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: List of gifts
        "401":
          description: Unauthorized
    post:
      summary: Create a new gift
      description: Initiates a gift sending process.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - recipient
                - amount
                - currency
              properties:
                recipient:
                  type: string
                  format: uuid
                amount:
                  type: number
                currency:
                  type: string
                message:
                  type: string
                template:
                  type: string
      responses:
        "201":
          description: Gift created, pending OTP
        "400":
          description: Bad request
        "401":
          description: Unauthorized
        "422":
          description: Validation error

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