Gauzy Integration

Relevant source files

The following files were used as context for generating this wiki page:

• apps/api/src/module/gauzy/gauzy.module.ts
• apps/api/src/module/gauzy/services/gauzy-auth.service.ts
• apps/api/src/module/gauzy/services/gauzy-upload.service.ts
• apps/api/src/module/gauzy/services/gauzy-user.service.ts
• apps/api/src/module/gauzy/services/gauzy-rest.service.ts
• apps/api/src/module/gauzy/interfaces/gauzy.model.ts
• apps/api/src/module/auth/services/update-user-profile/state/gauzy-update-user-profile.state.ts

The Gauzy integration is a NestJS module within the ever-rec API that serves as a client for an external Gauzy backend service. Its primary purpose is to abstract all communication with the Gauzy API, providing a clean, service-oriented interface for handling authentication, user profile management, and file uploads. This module acts as a bridge, translating requests from the ever-rec application into the appropriate REST API calls to the Gauzy system.

The integration is designed to be conditionally available based on configuration. A GAUZY_AVAILABLE provider checks for the presence of a Gauzy API URL in the environment settings, allowing the rest of the application to gracefully handle cases where the Gauzy backend is not configured.

Sources: apps/api/src/module/gauzy/gauzy.module.ts:22-28

Architecture and Core Components

The GauzyModule encapsulates all logic for interacting with the Gauzy API. It imports the HttpModule for making HTTP requests and ConfigModule for configuration, and it exports a set of services that constitute its public API within the ever-rec backend.

Sources: apps/api/src/module/gauzy/gauzy.module.ts:1-35

Key Services

Service	Description
GauzyRestService	A generic wrapper around HttpService that handles making REST calls (GET, POST, PUT, etc.) to the Gauzy API.
GauzyAuthService	Manages all authentication-related interactions, such as login, registration, and token refresh.
GauzyUserService	Handles user-specific operations, primarily updating user profiles.
GauzyUploadService	Manages file uploads for various media types like videos, screenshots, and audio clips.
HeaderBuilderService	A utility service responsible for constructing the necessary HTTP headers for authenticated requests.
GauzyUploadAssetService	(Declared but usage not detailed in provided files) Likely related to asset management post-upload.

Sources: apps/api/src/module/gauzy/gauzy.module.ts:15-21

Component Diagram

The following diagram illustrates the internal structure of the GauzyModule and its dependencies.

REST Communication (GauzyRestService)

The GauzyRestService is the foundation for all communication with the Gauzy API. It acts as a thin wrapper around nestjs-http-promise's HttpService, providing standardized methods for GET, POST, PUT, DELETE, and PATCH requests.

The service retrieves the base apiUrl for the Gauzy backend from the configuration and prepends it to all outgoing request paths. It also includes basic error logging for failed API calls.

Sources: apps/api/src/module/gauzy/services/gauzy-rest.service.ts

Request Flow

This diagram shows the flow of a typical request made through the GauzyRestService.

Authentication (GauzyAuthService)

GauzyAuthService handles the full lifecycle of user authentication against the Gauzy backend. It uses GauzyRestService to interact with specific endpoints on the Gauzy API.

Key Methods and Endpoints

Method	HTTP Method	Gauzy API Endpoint	Description
login	POST	auth/login	Authenticates a user with credentials.
register	POST	auth/register	Creates a new user account.
refreshToken	POST	auth/refresh-token	Obtains a new access token using a refresh token.
requestPassword	POST	auth/request-password	Initiates a password reset flow for a user.
changePassword	POST	auth/reset-password	Sets a new password for the user.

Sources: apps/api/src/module/gauzy/services/gauzy-auth.service.ts:16-35

Registration Flow

During registration, the GauzyAuthService uses GauzyMapper to transform the incoming registration data into the format expected by the Gauzy API before sending the request.

User Profile Management (GauzyUserService)

The GauzyUserService is responsible for user-related operations, specifically updating a user's profile information in the Gauzy backend.

The updateProfile method takes a user ID and the new profile data. It validates the inputs, builds a payload containing only the fields to be updated, constructs the necessary authentication headers, and sends a PUT request to the user/:id endpoint. A key part of this process is the use of GauzyMapper.parseFullName to split a fullName string into firstName and lastName, as required by the Gauzy API.

Sources: apps/api/src/module/gauzy/services/gauzy-user.service.ts:20-38, apps/api/src/module/auth/services/update-user-profile/state/gauzy-update-user-profile.state.ts:12-23

Profile Update Flow

File Uploads (GauzyUploadService)

The GauzyUploadService provides a unified interface for uploading different types of media to the Gauzy backend. It supports videos, screenshots, camera shots, and sound shots.

For each upload type, the service:

1. Constructs a FormData object.
2. Appends the file buffer and its metadata (filename, contentType, size).
3. Appends common metadata like tenantId, organizationId, and recordedAt.
4. Appends type-specific metadata (e.g., resolution for videos, timeSlotId for screenshots).
5. Uses HeaderBuilderService to generate authentication headers.
6. Calls the appropriate endpoint via GauzyRestService.

Sources: apps/api/src/module/gauzy/services/gauzy-upload.service.ts

Generic Upload Process

Data Models and Mappers

The gauzy.model.ts file defines the data contracts for interacting with the Gauzy API. It also contains the GauzyMapper class, which is a critical component for translating data between the ever-rec and Gauzy domains.

Sources: apps/api/src/module/gauzy/interfaces/gauzy.model.ts

IGauzyUser Interface

This interface represents the structure of a user object as returned by the Gauzy API.

Field	Type	Description
id	string?	The unique identifier for the user.
name	string?	The user's name.
email	string?	The user's email address.
fullName	string?	The user's full name.
imageUrl	string?	URL for the user's profile picture.
isEmailVerified	boolean?	Flag indicating if the email is verified.
tenantId	string?	The ID of the tenant the user belongs to.

Sources: apps/api/src/module/gauzy/interfaces/gauzy.model.ts:15-28

GauzyMapper Class

The GauzyMapper class provides static methods to convert data structures.

• toPersistence(input: IRegisterProps): Converts ever-rec's registration object to the IGauzyRegisterProps format required by the Gauzy API. This includes parsing a username into firstName and lastName.
• toUser(user: IGauzyUser): Converts a IGauzyUser object from Gauzy into the IUser format used within the ever-rec application.
• parseFullName(fullName: string): A utility to split a full name string into first and last name components.

Sources: apps/api/src/module/gauzy/interfaces/gauzy.model.ts:38-75

// Example of data transformation in GauzyMapper
export class GauzyMapper {
  public static toPersistence(input: IRegisterProps): IGauzyRegisterProps {
    const { firstName, lastName } = this.parseFullName(input.username);

    return {
      password: input.password,
      confirmPassword: input.password,
      user: {
        email: input.email,
        firstName,
        lastName,
        preferredLanguage: "en"
      }
    };
  }
  // ... other methods
}

Sources: apps/api/src/module/gauzy/interfaces/gauzy.model.ts:40-52