openapi: 3.0.3
info:
  title: NovaFacies Open Source Project - Module 'Users' v1
  description: >-
    API specification for Module 'Users' in NovaFacies Open Source Project. For
    more information, see https://novafacies.org
  version: 1.0.0
  contact:
    name: NovaFacies Open Source Foundation
    url: https://novafacies.org/
    email: support@novafacies.org
  license:
    name: GNU GPLv3
    url: https://www.gnu.org/licenses/gpl-3.0.html
  x-filename-json: users_api_v1.0.0.json
  x-filename-yaml: users_api_v1.0.0.yaml
  x-filename-html: users_api_v1.0.0.html
servers:
  - url: https://api.users.novafacies.com/v1
    description: Production server
  - url: https://staging.api.users.novafacies.com/v1
    description: Staging server
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        This API expects a valid JWT token in the Authorization header. The
        authentication mechanism, including token issuance and validation, is
        handled by the Auth Module.
security:
  - BearerAuth: []
paths:
  /users/create:
    post:
      summary: >-
        Creates a new user. Reference function with internal name:
        users.createUser
      description: >-
        Creates a new user. Reference function with internal name:
        users.createUser
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                  description: See Module Description
                middle_name:
                  type: string
                  description: See Module Description
                last_name:
                  type: string
                  description: See Module Description
                salutation:
                  type: string
                  description: See Module Description
                date_of_birth:
                  type: string
                  description: See Module Description
                email:
                  type: string
                  description: See Module Description
                address_name:
                  type: string
                  description: See Module Description
                street_address_1:
                  type: string
                  description: See Module Description
                street_address_2:
                  type: string
                  description: See Module Description
                city:
                  type: string
                  description: See Module Description
                state_region:
                  type: string
                  description: See Module Description
                postal_code:
                  type: string
                  description: See Module Description
                country:
                  type: string
                  description: See Module Description
              required:
                - first_name
                - last_name
                - email
                - address_name
                - street_address_1
                - city
                - state_region
                - postal_code
                - country
            examples:
              validRequest:
                value:
                  first_name: John
                  middle_name: A.
                  last_name: Doe
                  salutation: Mr.
                  date_of_birth: '1990-01-01'
                  email: john.doe@example.com
                  address_name: Home
                  street_address_1: 123 Main St
                  street_address_2: Apt 4B
                  city: New York
                  state_region: NY
                  postal_code: '10001'
                  country: US
      responses:
        '200':
          description: success
          content:
            application/json:
              examples:
                success:
                  value:
                    status: success
                    user_id: 1234-abcd
        '400':
          description: error
          content:
            application/json:
              examples:
                badRequest:
                  value:
                    message: error
  /users/get:
    get:
      summary: >-
        Retrieves details for an existing user. Reference function with internal
        name: users.getUser
      description: >-
        Retrieves details for an existing user. Reference function with internal
        name: users.getUser
      operationId: getUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: See Module Description
              required:
                - user_id
            examples:
              validRequest:
                value:
                  user_id: 1234-abcd
      responses:
        '200':
          description: success
          content:
            application/json:
              examples:
                success:
                  value:
                    status: success
                    user_id: 1234-abcd
                    first_name: John
                    middle_name: A.
                    last_name: Doe
                    salutation: Mr.
                    date_of_birth: '1990-01-01'
                    email: john.doe@example.com
                    user_is_soft_deleted: false
                    user_is_permanently_deleted: false
                    address_id: addr-5678
                    address_name: Home
                    street_address_1: 123 Main St
                    street_address_2: Apt 4B
                    city: New York
                    state_region: NY
                    postal_code: '10001'
                    country: US
                    address_is_soft_deleted: false
                    address_is_permanently_deleted: false
        '400':
          description: error
          content:
            application/json:
              examples:
                badRequest:
                  value:
                    message: error
  /users/getUserID:
    post:
      summary: >-
        Retrieves UserID by querying unique fields. Reference function with
        internal name: users.getUserID
      description: >-
        Retrieves UserID by querying unique fields. Reference function with
        internal name: users.getUserID
      operationId: getUserID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: See Module Description
              required:
                - email
            examples:
              validRequest:
                value:
                  email: john.doe@example.com
      responses:
        '200':
          description: success
          content:
            application/json:
              examples:
                success:
                  value:
                    status: success
                    user_id: 1234-abcd
        '400':
          description: error
          content:
            application/json:
              examples:
                badRequest:
                  value:
                    message: error
  /users/update:
    put:
      summary: >-
        Updates user details. Reference function with internal name:
        users.updateUser
      description: >-
        Updates user details. Reference function with internal name:
        users.updateUser
      operationId: updateUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: See Module Description
                first_name:
                  type: string
                  description: See Module Description
                middle_name:
                  type: string
                  description: See Module Description
                last_name:
                  type: string
                  description: See Module Description
                salutation:
                  type: string
                  description: See Module Description
                date_of_birth:
                  type: string
                  description: See Module Description
                email:
                  type: string
                  description: See Module Description
                address_id:
                  type: string
                  description: See Module Description
                address_name:
                  type: string
                  description: See Module Description
                street_address_1:
                  type: string
                  description: See Module Description
                street_address_2:
                  type: string
                  description: See Module Description
                city:
                  type: string
                  description: See Module Description
                state_region:
                  type: string
                  description: See Module Description
                postal_code:
                  type: string
                  description: See Module Description
                country:
                  type: string
                  description: See Module Description
              required:
                - user_id
            examples:
              validRequest:
                value:
                  user_id: 1234-abcd
                  first_name: John
                  middle_name: A.
                  last_name: Doe
                  salutation: Mr.
                  date_of_birth: '1990-01-01'
                  email: john.doe@example.com
                  address_id: addr-5678
                  address_name: Home
                  street_address_1: 123 Main St
                  street_address_2: Apt 4B
                  city: New York
                  state_region: NY
                  postal_code: '10001'
                  country: US
      responses:
        '200':
          description: success
          content:
            application/json:
              examples:
                success:
                  value:
                    status: success
        '400':
          description: error
          content:
            application/json:
              examples:
                badRequest:
                  value:
                    message: error
  /users/delete:
    delete:
      summary: >-
        Permanently deletes a user. Reference function with internal name:
        users.deleteUser
      description: >-
        Permanently deletes a user. Reference function with internal name:
        users.deleteUser
      operationId: deleteUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: See Module Description
              required:
                - user_id
            examples:
              validRequest:
                value:
                  user_id: 1234-abcd
      responses:
        '200':
          description: success
          content:
            application/json:
              examples:
                success:
                  value:
                    status: success
        '400':
          description: error
          content:
            application/json:
              examples:
                badRequest:
                  value:
                    message: error
  /users/softDelete:
    post:
      summary: >-
        Soft deletes a user. Reference function with internal name:
        users.softDeleteUser
      description: >-
        Soft deletes a user. Reference function with internal name:
        users.softDeleteUser
      operationId: softDeleteUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: See Module Description
              required:
                - user_id
            examples:
              validRequest:
                value:
                  user_id: 1234-abcd
      responses:
        '200':
          description: success
          content:
            application/json:
              examples:
                success:
                  value:
                    status: success
        '400':
          description: error
          content:
            application/json:
              examples:
                badRequest:
                  value:
                    message: error
  /users/list:
    get:
      summary: >-
        Lists users with pagination. Reference function with internal name:
        users.listUsers
      description: >-
        Lists users with pagination. Reference function with internal name:
        users.listUsers
      operationId: listUsers
      responses:
        '200':
          description: success
          content:
            application/json:
              examples:
                success:
                  value:
                    status: success
                    users:
                      - user_id: 1234-abcd
                        first_name: John
                        middle_name: A.
                        last_name: Doe
                        salutation: Mr.
                        date_of_birth: '1990-01-01'
                        email: john.doe@example.com
                        user_is_soft_deleted: false
                        user_is_permanently_deleted: false
                        address_id: addr-5678
                        address_name: Home
                        street_address_1: 123 Main St
                        street_address_2: Apt 4B
                        city: New York
                        state_region: NY
                        postal_code: '10001'
                        country: US
                        address_is_soft_deleted: false
                        address_is_permanently_deleted: false
                      - user_id: 5678-efgh
                        first_name: Jane
                        middle_name: B.
                        last_name: Smith
                        salutation: Ms.
                        date_of_birth: '1985-06-15'
                        email: jane.smith@example.com
                        user_is_soft_deleted: false
                        user_is_permanently_deleted: false
                        address_id: addr-9876
                        address_name: Office
                        street_address_1: 456 Business Rd
                        street_address_2: Suite 100
                        city: San Francisco
                        state_region: CA
                        postal_code: '94107'
                        country: US
                        address_is_soft_deleted: false
                        address_is_permanently_deleted: false
                    total: 100
        '400':
          description: error
          content:
            application/json:
              examples:
                badRequest:
                  value:
                    message: error
  /users/search:
    post:
      summary: >-
        Searches users by name, email, or other criteria. Reference function
        with internal name: users.searchUsers
      description: >-
        Searches users by name, email, or other criteria. Reference function
        with internal name: users.searchUsers
      operationId: searchUsers
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: See Module Description
                first_name:
                  type: string
                  description: See Module Description
                middle_name:
                  type: string
                  description: See Module Description
                last_name:
                  type: string
                  description: See Module Description
                salutation:
                  type: string
                  description: See Module Description
                date_of_birth:
                  type: string
                  description: See Module Description
                email:
                  type: string
                  description: See Module Description
                user_is_soft_deleted:
                  type: boolean
                  description: See Module Description
                user_is_permanently_deleted:
                  type: boolean
                  description: See Module Description
                address_id:
                  type: string
                  description: See Module Description
                address_name:
                  type: string
                  description: See Module Description
                street_address_1:
                  type: string
                  description: See Module Description
                street_address_2:
                  type: string
                  description: See Module Description
                city:
                  type: string
                  description: See Module Description
                state_region:
                  type: string
                  description: See Module Description
                postal_code:
                  type: string
                  description: See Module Description
                country:
                  type: string
                  description: See Module Description
                address_is_soft_deleted:
                  type: boolean
                  description: See Module Description
                address_is_permanently_deleted:
                  type: boolean
                  description: See Module Description
            examples:
              validRequest:
                value:
                  first_name: John
                  email: john.doe@example.com
      responses:
        '200':
          description: success
          content:
            application/json:
              examples:
                success:
                  value:
                    status: success
                    results:
                      - user_id: 1234-abcd
                        first_name: John
                        middle_name: A.
                        last_name: Doe
                        salutation: Mr.
                        date_of_birth: '1990-01-01'
                        email: john.doe@example.com
                        user_is_soft_deleted: false
                        user_is_permanently_deleted: false
                        address_id: addr-5678
                        address_name: Home
                        street_address_1: 123 Main St
                        street_address_2: Apt 4B
                        city: New York
                        state_region: NY
                        postal_code: '10001'
                        country: US
                        address_is_soft_deleted: false
                        address_is_permanently_deleted: false
                      - user_id: 5678-efgh
                        first_name: Jane
                        middle_name: B.
                        last_name: Smith
                        salutation: Ms.
                        date_of_birth: '1985-06-15'
                        email: jane.smith@example.com
                        user_is_soft_deleted: false
                        user_is_permanently_deleted: false
                        address_id: addr-9876
                        address_name: Office
                        street_address_1: 456 Business Rd
                        street_address_2: Suite 100
                        city: San Francisco
                        state_region: CA
                        postal_code: '94107'
                        country: US
                        address_is_soft_deleted: false
                        address_is_permanently_deleted: false
        '400':
          description: error
          content:
            application/json:
              examples:
                badRequest:
                  value:
                    message: error
  /users/validate:
    post:
      summary: >-
        Checks if a user exists by email. Reference function with internal name:
        users.validateUserExists
      description: >-
        Checks if a user exists by email. Reference function with internal name:
        users.validateUserExists
      operationId: validateUserExists
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: See Module Description
              required:
                - email
            examples:
              validRequest:
                value:
                  email: john.doe@example.com
      responses:
        '200':
          description: success
          content:
            application/json:
              examples:
                success:
                  value:
                    status: success
                    exists: true
        '400':
          description: error
          content:
            application/json:
              examples:
                badRequest:
                  value:
                    message: error
