appsuite-shared

This repository contains all the classes and functions used in the applications:

• Portfolio
• Campaign
• Licenses

To use it in applications you must publish it as an npm package and add it to applications in package.json:

{
  "dependencies": {
    "appsuite-shared": "0.0.104"
  }
}

Exporting as npm package

To export it as an npm package, set the package version in package.json:

{
  "name": "appsuite-shared",
  "version": "0.0.104",
}

Create the package:

npm run build:

Publish in npm:

npm publish

Dependencies

If any function or class uses third-party dependencies, it must be added in package.json:

{
  "peerDependencies": {
    "auth0": "^3.0.1",
  }
}

Local development

To test before to create package and publish to npm package repository is need follow these commands:

in appsuite-shared directory:

npm link

in the app directory

npm link appsuite-shared

Remember after any change the code execute:

npm run build

Services response

Classes to be used in any application must send a response using the setServiceSuccessResponse function. The parameters are:

• details (optional): is an array of strings, each element is a detail of the process.
• message (optional): is a string, message to the user
• payload: the data to be used in the back-end or front-end application
• status (optional):: the response code

Handle exceptions

Our exception handling works primarily through propagation: An exception passes from one method to another until a method must return a response to the user in the form of an object. There are two types of exceptions:

• Exceptions from third-party services: These exceptions are thrown by third-party services (AWS, Auth0, among others)
• Local exceptions: These exceptions are thrown by services or methods created by the DPS team. ​

Manage exceptions

Exception handling is done through the try-catch block. To use try-catch consider the following:

1. All functions that working with services (queries to external services, queries to other services, queries to databases) or async operations (read, write or delete file) must have try-cath block:

try {
	// code
} catch (error) {
	console.error(error)
}

2. There should be, as far as possible, classes that bring together the use of external services (for example: a class that contains all the S3 methods)
3. Classes that contain external services or those that communicate with third-party services must use the throwExternalServiceError function to throw exceptions.

// If it is a class you must create a method that uses the throwExternalServiceError function

this.throwError = function ({ error, methodName }) {
	throwExternalServiceError({
		error,
		methodName,
		serviceName: this.constructor?.name,
	})
}

// error is the catch block error parameter
// methodName is the method that is throwing the exception
// serviceName is the name of the class where the exception is being thrown

try {
	const client = new S3Client({
		region: this.region,
		credentials: {
			accessKeyId: this.accessKeyId,
			secretAccessKey: this.secretAccessKey,
		},
	})

	return client
} catch (error) {
	this.throwError({
		error,
		methodName: 'getClient',
	})
}

4. Functions that use external services must use the throwExternalServiceError function

const getUser = async (userId) => {
	try {
		const user = await serviceGetUser(userId)
	} catch (error) {
		throwExternalServiceError({
			error,
			serviceName: 'getUser ',
		})
	}
}

5. For classes that do not bind external services, they must use the throwLocalError function to make their own method to throw local exceptions:

this.throwLocalError = ({ methodName, error }) => {
	throwLocalError({
		error,
		methodName,
		serviceName: this.constructor?.name,
	})
}

// If it will be used in a method, only use the function throwLocalError
try {
	// code
} catch (error) {
	throwLocalError({
		error,
		methodName: 'my function',
	})
}

6. If the method of a class is complex, being prone to errors, provision should be made to throw local exceptions.

try {
	const curProjectName = this.projectName ? `-${this.projectName}` : ''
	const fnExt = fileName.split('.').pop()
	const curfileName = `${dsdCrypto.hashSHA256(
		auth0UserId
	)}-${type}${curProjectName}.${fnExt}`
	const imgBuffer = await fsReadFile(url)
	const respUpload = await this.manageFilesAws.uploadFile({
		bucket: this.s3Bucket,
		data: imgBuffer,
		key: `${this.s3Bucket}/${curfileName}`,
	})
	fsRemoveFile(url)

	return respUpload
} catch (error) {
	if (error instanceof ExternalServicesError) throw error

	this.throwLocalError({ methodName: 'uploadImage', error })
}

Error response

To send the exception to the front-end the setServiceErrorResponse function must be used. In a class a method must be created using that function:

this.setServiceErrorResponse = ({
	details,
	message = messages.genericErrorCustomTheme,
	stack,
	status,
}) => {
	return setServiceErrorResponse({
		isDev: true,
		details,
		message,
		stack,
		status,
	})
}

setServiceErrorResponse has the isDev parameter, with this parameter set to true the response includes the exception stack. In classes the isDev must be set in the constructor.