@flytio/int-error-helper

Error helper for integrations

Use this package to standardize the error codes and make good and actionable error messages for order injection failures.

The methods exported by this package will help you to build the error object on the OrderResponse that must be returned by a the gRPC methods in the order integration.

NOTE: This helper is only working for the order integrations at the moment, but the name has been left generic because it could easily be extended to cover the sync menu errors in the future.

What is an actionable error message?

An error message should contain as much information as possible to help who sees the error to take an action to promptly fix it.

A bad error message, for example, is the following:

There was an unknown error sending the order to the POS.

While a good one is, for example:

There is an invalid item in the payload, please contact the menu team to confirm the PLUs are correct. POS Error message: [-956234774] Invalid database object detected: 1234

This message is composed by three parts:

1. A text explaining the error occurred
2. Who need to be contacted to investigate / fix the problem
3. The original POS error message

With a well defined error message like the above one, who spots the error knows immediately what the problem is and how to act in order to fix it.

Why using an npm module for that?

We decided to create a module in order to unify the error codes and messages returned by the various integrations. We want, for example, that the error messages for an invalid tender type will be the same across all the integrations.

When I should use this module?

You should use this module in every integration you're developing. What you need to do on your integration is investigating on the error response returned from the POS and call this module methods that will create the error object (required in the OrderResponse) for you, with no hassle required to make sure they are the same all across the integrations.

Usage

Install

Install the package using yarn:

yarn add @flytio/int-error-helper

How to use in in your integration

In order to use this helper in your integration, you must first register it. This will load some pre-defined errors that are ready to be used in your integration without any additional setup.

To register the error helper:

import { IntegrationErrorResponseRegister } from "@flytio/int-error-helper";

const integrationErrorResponse = new IntegrationErrorResponseRegister(); 

Once you have your error response register, you can use the buildFor method with one of the pre-defined error types to build the error object of an OrderResponse:

import { OrderResponseStatus } from '@flytio/protos';
import { defaultErrors } from '@flytio/int-error-helper';

const error = integrationErrorResponse.buildFor(
    defaultErrors.MalformedRequest,
    "This is what happened in the POS",
);

return {
    status: OrderResponseStatus.Rejected,
    can_retry: false,
    happened_at: `${Date.now() / 1000}`,
    error: error,
  };

Pre defined errors:

There are currently 4 pre-defined errors that are registered during the creation of the IntegrationErrorResponseRegister. These are:

Error Mapping	error.code	error.message
MenuError	MENU_ERROR	There was an error with and item sent to the POS, contact the menu team to confirm the PLUs are correct.
Unknown	UNKNOWN	Unknown Pos Error, contact the Flyt dev team for support
TenderError	TENDER_ERROR	Tender type was not found in POS, contact the POS company for support
MalformedRequest	MALFORMED_REQUEST	The request sent to the POS is malformed, contact the Flyt dev team for support.

Where:

• Error Mapping: Defines one of the value of the defaultErrors exported by this package

• error.code: It's one of the ones defined by the protos here. If the Error Mapping code is not resolved in any of the ones allowed by the protos, will be returned the UNKNOWN one by default.

• error.message: Defines how the error message is built for that kind of error.

  Please not that everyone of these errors will attached the original POS error message if passed as optional parameter to the buildFor function.

So, for example, the error returned for the malformed request is:

{
    "code":"MALFORMED_REQUEST",
    "message":"The request sent to the POS is malformed, contact the Flyt dev team for support. Original POS message: This is what happened in the POS",
}

Extending the error messages with a custom one

Extending the register to override or handle different kind of errors in an integration is easy.

You can register a new error or override one of the pre-defined one by using the registerNewError method of the IntegrationErrorResponseRegister.

What you need to do is creating a variable that implements the ErrorMessage interface that will defined how the error message is structured, and pass it to the registerNewError function with the error code that should map one of the available ones to be returned. Note that in this case the error code returned will be UNKNOWN

For example, if you want to handle an error that is not defined by this module, what you need to do is:

import { ErrorMessage } from '@flytio/int-error-helper';

const errorToRegister = (originalPosErrorMessage?: string): ErrorMessage => {
    return {
        actionMessage: 'This is what happened',
        actionSubject: 'this is who should fix it',
        originalPosMessage: originalPosErrorMessage,
    
        toString(): string {
            return `${this.actionMessage} and ${this.actionSubject}. Original POS message: ${originalPosErrorMessage}`;
        },
    };
};

integrationErrorResponse.registerNewError('customError', errorToRegister);

Then, building the error is exactly the same as for the pre-defined ones:

const error = integrationErrorResponse.buildFor('customError', 'this is the problem occurred');

This example above will return the following error object:

{
    "code": "UNKNOWN",
    "message": "This is what happened and this is who should fix it. Original POS message: this is the problem occurred"
}

To override one of the pre defined errors, you need to do exactly the same thing, with the only difference that you need to pass a defaultError enum value to the registerNewError method. For example:

import { defaultErrors } from '@flytio/int-error-helper';

integrationErrorResponse.registerNewError(defaultErrors.MalformedRequest, errorToRegister);

Please look at the test file for more examples on the usage.